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About This Book 



NetView Customization: Using PUI and C describes how a system programmer can 
tailor or supplement the NetView™ program to satisfy unique requirements or 
operating procedures. 

This manual discusses the usage and advantages of user-written programs (exit 
routines, command processors, and subtasks.) It provides instructions that guide 
the programmer through the mechanics of designing, writing, and installing these 
programs. 

This book primarily contains general-use programming interfaces, which allow the 
customer to write programs that use the services of NetView. However, the book 
also provides the following types of information, which are explicitly identified 
where they occur: 

Installation exits and other product-sensitive interfaces are provided to allow the 
customer installation to perform tasks such as product tailoring, monitoring, mod- 
ification or diagnosis. They are dependent on the detailed design or implementa- 
tion of the product. Such interfaces should be used only for these specialized 
purposes. Because of their dependencies on detailed design and implementation, 
it is to be expected that programs written to such interfaces may need to be 
changed in order to run with new product releases or versions, or as a result of 
service. 

The following is a list of common terms used in this book. 

Command List 

A list of commands and statements designed to perform a specific function for 
the user. Command lists can be written in rexx or in NetView command list 
language. 

Command Procedure 

Either a command processor written in a high-level language (hll) or a 
command list. See command processor and command list for further explana- 
tion. 

Command Processor 

A user-written module designed to perform a specific function. Command 
processors, which can be written in assembler or a high-level language (hll), 
are invoked as commands. 

Hlgh-Level Language (HLL) 

A programming language that does not reflect the structure of any particular 
computer or operating system. For NetView Release 3, the high-level lan- 
guages are pl/i and c. 

NetView Command List Language 

An interpretive language unique to NetView that is used to write command 
lists. 
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REXX 

Restructured Extended Executor Language. An interpretive language used to 
write command lists. 

User Exit Routine 

A user-written routine that receives control at predefined user exit points. 
User exit routines can be written in assembler or a high-level language (HLL). 



Who Should Use This Book 



This book is intended for experienced system programmers who are knowledge- 
able in pl/i or c. It is assumed that the user is already familiar with the functions 
that NetView provides. 

Secondary users include operators, network planners, designers, and systems 
analysts, as well as ibm marketing representatives and instructors. 
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Where To Find More Information 



The following list shows all of the publications in the NetView Release 3 library, 
arranged according to related tasks. For more information on these and other 
related publications, see "Bibliography" on page 337. 

Evaluation and Education 

Network Program Products General Information GC30-3350 

Bibliography and Master Index for NetView, NCP, and VTAM GC31-6081 

Learning about NetView: Operator Training (pc Diskettes) SK2T-0292 
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Console Automation Using NetView: Planning 



SC30-3351 
SK2T-1988 
SC31-6058 



Installation and Administration 

NetView Installation and Administration Guide 
NetView Administration Reference 
Network Program Products Samples 
NetView Tuning Guide 



SC31-6018 
SC31-6014 
SC30-3352 
SC31-6079 



Customization 

NetView Customization Guide 
NetView Customization: Writing Command Lists 
NetView Customization: Using PLII and C 
NetView Customization: Using Assembler 



SC31-6016 
SC31-6015 
SC31-6037 
SC31-6078 



Operation 

NetView Operation Primer 
NetView Operation 
NetView Command Summary 



SC31-6020 
SC31-6019 
SX75-0026 



Diagnosis 

NetView Problem Determination and Diagnosis LY43-0001 

NetView Resource Alerts Reference SC31-6024 

NetView Problem Determination Supplement for LD21-0023 

Management Services Major Vectors 0001 and 0025 
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Chapter 1. NetView High-Level Language Services 



Before reading this chapter, you should have read the chapters on designing user- 
written functions and the NetView™ customization facilities in the NetView 
Customization Guide. You should also have NetView experience as well as pro- 
gramming experience in pl/i ore. 

To use this manual most effectively, you should have in mind a specific command 
processor or user exit routine that you want to write in pl/i or c. For example, you 
might want to write a command processor to run under a Data Services Task (dst) 
to store data in a vsam file or a command processor to run on an Operator Station 
Task (ost) to display information on an operator's screen. The NetView 
Customization Guide contains information to help you decide the command 
processors and user exit routines you need to write in order to build your applica- 
tion and the appropriate language to use for each of these routines. 

This chapter discusses the NetView services available to you for designing your 
command processor or user exit routine. The following is the list of services dis- 
cussed in this chapter: 

Synchronous Command Execution 

Sending Commands (Asynchronous Command Execution) 

Client/Server Request/Response Handling 

Operator Interaction 

Data Access 

Communications Network Management Interface 

NetView Partitioned Data Sets 

NetView Storage Access 

User-Defined Lock Management 

Parsing Character Strings 

Scope Checking 

NetView Message Logging 

Debugging Support 



Synchronous Command Execution 



High-Level Language (hll) command processors may invoke any NetView 
command, including simple commands, command lists, rexx command proce- 
dures, assembler command processors, NetView applications such as Session 
Monitor, and other hll command processors. The command must be executable in 
the calling environment. For example, data services commands can only be 
invoked from a data services command processor. 
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Sending Commands (Asynchronous Command Execution) 



hll user exit routines cannot invoke NetView commands directly. However, all hll 
command processors and user exit routines can schedule NetView commands to 
be executed asynchronously under any NetView task. 



Client/Server Request/Response Handling 



NetView currently supports server tasks that service and reply to requests from 
one or more operator tasks. The current level of support is accomplished by: 

• Allowing the requesting command processor to wait pseudo-synchronously for 
the reply. This means that the requesting command processor suspends proc- 
essing while waiting for the reply. The task is not suspended and may con- 
tinue processing other commands. The suspended command processor 
resumes processing after receiving the reply. 

• Allowing the requests and replies to be sent over NetView-to-NetView cross 
domain operator sessions. 

• Correlating the reply with the correct activation of the requesting hll command 
processor. This in turn allows multiple active instances of the requesting 
command processor under a single operator task. 



Operator Interaction 

The following describes operator interaction in line mode and full-screen mode. 

Line Mode Output 

hll command processors and most user exit routines can send output to the fol- 
lowing destinations: 

• A NetView operator 

• The operating system console 

• Another task 

• The authorized receiver 

• A group of operators defined by the NetView assign command. 

Multi-line messages may be sent as a single unit (mlwto) so an operator will 
receive them in a sequence without messages from other sources interspersed. 
This type of output will appear on the command facility screen or on the operating 
system console. 



Line Mode Input 



hll command processors running under an ost, nnt, or ppt task may accept line 
mode input from an operator. This function is similar to that provided by the 
NetView command list language &pause statement, except that the hll command 
processor may continue to run while waiting for operator input. To avoid forcing 
the operator to know what language a command procedure is written in, the go 
command is used to provide input to a command procedure written in the NetView 
command list language, rexx, and High-Level Language. 
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Full-Screen Input/Output 

hll command processors may invoke the NetView view command to provide full- 
screen interaction with an operator. This function is similar to the use of the view 
command from a command list. The capability to roll among NetView applica- 
tions, including hll command processors, is also available, hll command 
processors are treated like command lists when determining roll groups. The 
capability to asynchronously update a panel while it is being displayed is provided. 

Data Access 

The following is an overview describing data access techniques available to an hll 
command processor or user exit routine. These techniques include: 

• Message Trapping 

• Message Automation 

• Command List Variable Access 

• NetView Information 

• VSAM Files 

• Data Queue Manipulation 

Message Trapping 

Command procedures frequently need to intercept or trap and process messages 
that would ordinarily go to an operator. The NetView hll Application Programming 
Interface (api) provides this function for single and multi-line messages. 

Message Automation 

NetView allows hll command processors to be invoked upon receipt of messages 
and provides the command processor with access to both the command, and to the 
message that invoked it. Multi-line messages are supported here as well. NetView 
also provides services to alter the contents of the messages. 

Command List Variable Access 

Command procedures frequently store data in task global and common global 
command list variables which can be accessed by other command procedures, hll 
command processors and user exit routines can access and update these vari- 
ables. 

NetView Information 

hll command processors and user exit routines may query certain information 
(such as domain id, message attributes, etc.) about the current NetView environ- 
ment. The information provided by this function is similar to that provided by 
control variables in the NetView command list language and control block fields in 
Assembler. 



VSAM Files 



hll data services command processors may read, write, update, and delete 
records in vsam files associated with the task under which the command processor 
is running. All requests are pseudo-synchronous allowing other command 
processors to execute while file i/o requests are executing. 
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Data Queue Manipulation 

This function allows an hll command processor or user exit routine to manipulate 
hll data queues. Each hll command processor and user exit routine has a set of 
queues from which it may receive data. There is a queue for each of the following 
types of input data: 

• Input from a NetView operator 

• Operator messages trapped for processing 

• Data from another hll command processor or user exit routine 

• Initial data associated with a message that caused an hll command processor 
or user exit routine to be executed. 

• Data solicited over the cnmi. 



Communications Network Management Interface 

hll data services command processors can send and receive data over the Com- 
munications Network Management Interface (cnmi). The cnmi is used to forward 
commands to and collect data from devices in the network. For example, rtm data 
is collected from PU2 control units using the cnmi. Unsolicited data received over 
the cnmi may be processed by hll command processors as well. Solicited 
requests are pseudo-synchronous. 



NetView Partitioned Data Sets 

hll command processors and user exit routines have read access to the NetView 
partitioned data sets. This allows you to write a program that uses the information 
that is in the NetView partitioned data sets. This function is completely synchro- 
nous. 

Dynamic File Allocation/Deallocation 

NetView provides facilities to dynamically allocate/deallocate files by the use of 
NetView allocate/free commands. (Refer to the NetView Operation manual for 
more details). Once allocated, these files may be accessed using the file i/o facili- 
ties present in the language being used. 



NetView Storage Access 



An hll command processor or user exit routine will be able to allocate and free a 
named storage pool from the NetView subtask under which it is running. A storage 
pool is composed of a primary storage block and related secondary blocks. Once a 
pool is allocated, individual storage cells within the pool may be accessed as 
needed by the hll command processor or user exit routine. The storage should be 
referenced only from the task associated with it. 



Storage Copying 



This function allows hll command processors and user exit routines to make a 
copy of any area of virtual storage in the NetView address space in which the hll 
command processor or user exit routine is running. If a request is made to copy an 
area of storage that is not currently addressable, a return code is generated 
instead of an 0C4 abend. This function is useful for debugging. The user must exer- 
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Named Storage 



cise great care to insure that the storage to which the copy is made belongs to 
their program. 



This function allows hll command processors or user exit routines to obtain an 
area of virtual storage and associate a name with it, so that other hll command 
processors and user exit routines running under the same task may access this 
area of storage. This function can be used by transaction-oriented applications to 
save data across transactions. 



User-Defined Lock Management 



hll command processors and user exit routines will be able to obtain, release and 
test the control of a named lock. The lock management scheme uses a simple 
alphanumeric hierarchy. Locking is useful when updating common global vari- 
ables or to serialize any other common resource. 



Parsing Character Strings 



A parsing service is provided as part of the pl/i language. This service is similar to 
the sscanf function available in the c language. It is intended to facilitate the 
parsing of commands and messages. 



Scope Checking 



hll command processors and user exit routines can invoke the NetView scope 
checking facility to determine whether a particular operator is authorized to issue a 
command with restricted operands or operand values. 



NetView Message Logging 



All hll command processors and most user exit routines can send message output 
to the following logs: 

• The network log 

• An external log (such as smf) 

• A sequential log 



Debugging Support 



The NetView hll api provides two debugging aids for users: an interactive 
debugger that displays the parameters and results of all hll api service routine inv- 
ocations, and a continuous First Failure Data Capture trace for abend debugging. 
In addition, the NetView internal trace may be used (see NetView Problem Determi- 
nation and Diagnosis for further detail). 
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Remote Interactive Debugger (RID) 

The remote interactive debugger (rid) allows NetView hll service routine calls to 
be trapped and displayed to the programmer, rid is implemented using NetView 
commands and messages so that debugging procedures may be created using 
NetView command list language, rexx, or hll command procedures. In addition, 
since NetView provides facilities to route commands and messages to remote 
systems, rid may be used from one system to debug an hll command processor or 
user exit routine running on another system. 

rid operates at the subtask level, so using rid to stop an hll command processor or 
user exit routine running under one subtask will not effect other subtasks in the 
same NetView address space. 

First Failure Data Capture Trace (FFDCT) 

Each hll command processor or user exit routine maintains an eight-entry 
continuously-wrapping trace area. Trace entries are recorded at entry to and exit 
from hll service routines and at other key points inside the hll routines. In the 
event of an abend, this area will give some indication of what was going on before 
the abend. Refer to the First Failure Data Capture Trace in the NetView Problem 
Determination and Diagnosis manual for further detail. 
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Chapter 2. HLL User Exit Routines 



You can write user exit routines to view, delete, or replace data flowing to, from, or 
through NetView. For example, your code can examine the messages passing 
through NetView, record relevant data, and initiate work requests based on the 
data. In addition, your code can delete any unnecessary message from further 
processing or substitute a modified message in place of the original message. 
Thus, user exit routines can handle a specific event with non-standard processing 
and automate processes based on message information. 

This chapter contains product-sensitive programming interfaces provided by 
NetView. Installation exits and other product-sensitive interfaces are provided to 
allow the customer installation to perform tasks such as product tailoring, moni- 
toring, modification or diagnosis. They are dependent on the detailed design or 
implementation of the product. Such interfaces should be used only for these spe- 
cialized purposes. Because of their dependencies on detail design and implemen- 
tation, it is to be expected that programs written to such interfaces may need to be 
changed in order to run with new product releases or versions, or as a result of 
service. 



Overview of User Exit Routines 

NetView provides two types of user exits for which you may write routines: 

• Global user exits (DSiExnn), which apply to all NetView tasks. The global user 
exit routines are loaded when NetView starts. See Table 1 on page 11 for a 
list of user exits. 

• Data Services Task (dst) user exits (xrrnn and bnjpalex), which apply only to 
dst subtasks. The dst user exit routines are loaded when their dst starts. 
Each dst can have its own set of user exit routines. 

Note: dst user exits should not be used under the Network Product Support (nps) 
task named dsigds. 

You should avoid coding user exits for frequently executed functions, such as vsam 
i/o, since performance can be degraded significantly. 

Each user exit handles a particular event, such as the reception of data from the 
system console. When that event occurs, NetView passes control to the appro- 
priate user exit routine for processing. After processing, the user exit routine 
returns control and passes a return code to NetView. Optionally, up to 10 dst exit 
routines can be concatenated. If the first exit did not indicate userdrop, NetView 
then calls the next one in the sequence. This process continues until the last dst 
exit has returned control to NetView. For more information on input to the user exit 
routines see Chapter 4 on page 27 or Chapter 8 on page 91. 

Coding Restrictions 

The following hll service routines cannot be invoked from any user exit: 

• CNMCMD 

• CNMCNMI 

• CNMKIO 
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cnmsmsg cannot be issued from dsiexo4 and dsiexo9. Only cnmsmsg with a destina- 
tion type of task can be issued from dsiexo2a. dsiexo2a, dsiexo4, and dsiexo9 will only 
be invoked in the mainline environment if written in hll. If written in assembler 
these exit routines can be invoked in both the mainline and irb exit environments. 
See NetView Customization: Using Assembler for additional information on exits 
running in the irb exit environment. 

General Return Codes 

Unless otherwise noted, user exit routines can pass the following return codes to 
NetView in the return code field (hlbrc for pl/i or Hlbrc for c) to indicate that the 
messages are to be unchanged, deleted, or replaced: 

Return Code Meaning 

userasis (0) Use the message as presented to the user exit; do not delete or 

replace it. 

userdrop (4) Delete the message from the terminal and from the network log, 

system log, and hardcopy log; stop processing before the 
message appears on the screen. For more information on how 
to delete messages, see "Deleting Messages." 

userswap (8) Replace the message with the modified cmdbuf (Cmdbuf). For 

more information on how to replace messages, see "Replacing 
Messages." 

Deleting Messages 

To delete a message entirely, use return code userdrop. 

When NetView receives a userdrop return code, no further exit routines are called. 
Thus, if you have concatenated dst exit routines, a userdrop return code prevents 
the next exit routine from being called. 

Replacing Messages 

To replace a message, use return code userswap and set the input cmdbuf 
{Cmdbuf) data to the desired data. The replacement data must be less than or 
equal in length to the original cmdbuf (Cmdbuf) data; otherwise it will be truncated 
to the original length of the cmdbuf (Cmdbuf) data. 

User exit dsiexo2A provides a more flexible interface for replacing messages using 
cnmaltd. See "CNMALTD (CNMALTDATA) - Alter Data On A Queue" on 
page 190. 

You can concatenate dst user exit routines when replacing messages. In this case, 
the buffer containing the replacement message becomes the input for the subse- 
quent dst user exit routine. Refer to NetView Customization: Using Assembler for 
message flows. 



10 NetView Customization: Using PLI and C 



The following table lists all hll user exits and the task environments they can be 
called under. 



Table 1. User Exit Environments 




Exit 


Description 


Applicable Tasks 


BNJPALEX 


Not supported in HLL 




DSIEX01 


Not supported in HLL 




DSIEX02A 


Message Output this Domain or 
Message Output Cross-Domain 


NNT, OST, PPT 
NNT, OST, 
CNMCSSIR 


DSIEX03 


input Before Command Processing 
HDRTYPEX Cross-Domain Return 
Command Receive 


NNT, OST, PPT 
NNT 


DSIEX04 


Log Output for Buffers not Processed 
by DSIEX02A 


Main Task or Any 
Subtask 


DSIEX05 


Before VTAM Command Invocation* 


NNT, OST, PPT 


DSIEX06 


Solicited VTAM Messages* 


NNT, OST, PPT 


DSIEX07 


Cross-Domain Command Send 


NNT, OST 


DSIEX09 


Output to the System Console 


Main Task or Any 
Subtask 


DSIEX10 


Input from the System Console 


Main Task 


DSIEX11 


Unsolicited VTAM Messages* 


PPT 


DSIEX12 


Logon Validation 


NNT, OST 


DSIEX13 


OST/NNT Message Receiver 


NNT, OST, PPT 


DSIEX14 


Before Logoff 


NNT, OST 


DSIEX16 


Not supported in HLL 




XITBN 


BSAM Empty File 


DST 


XITBO 


BSAM Output 


DST 


XITCI 


CNM Interface Input 


DST 


XITCO 


CNM Interface Output 


DST 


XITDI 


DST Initialization 


DST 


XITVI 


VSAM Input 


DST 


XITVN 


VSAM Empty File 


DST 


XITVO 


VSAM Output 


DST 


XITXL 


External Logging 


DST 



Note: 



When using NetView poi only. Does not include vtam messages from other 
sources; for example mvs/xa ssi. You can process these messages in 

DSIEX02A. 
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User Exits 

NetView provides a number of user exits. This section describes each of these 
user exits. For a discussion of message flows and interception points in ost, nnt, 
and ppt tasks see NetView Customization: Using Assembler. 

DSIEX01: Input from the Operator 

This exit is only available through assembler language. See NetView 
Customization: Using Assembler. 

DSIEX02A: Output to the Operator 

Description: NetView calls dsiexo2A for standard output to an operator's terminal. 
dsiexo2a runs before the device-dependent output is inserted and the data is 
logged. If dsiexo2A is called, dsiexo4 is not called since logging options may be 
specified in either dsiexo2A or in the message automation table. 

Example of Use: Since the message has been formatted but not yet displayed or 
logged, you can use dsiexo2a to delete or replace the message before it is auto- 
mated, logged, or displayed. 

If your messages will be translated (such as to Kanji), changes to the message text 
may affect the translations. (See NetView Installation and Administration Guide for 
more information.) 

Coding Considerations: Message automation is invoked after this exit routine has 
been called; therefore, any changes made for messages in this user exit may affect 
message automation. Message automation is not invoked for a message that has 
been deleted by this exit routine. 

Do not use the userswap return code to replace messages. Use the cnmaltd 
service. See "CNMALTD (CNMALTDATA) - Alter Data On A Queue" on page 190. 

dsiexo2a is supported only in 31-bit addressing mode. 

cnmsmsg can be issued from dsiexo2a but only with the destination type of 'task'. 
The message resulting from the cnmsmsg call will not redrive dsiexo2a. 

DSIEX03: Input Before Command Processing 

Description: All regular commands call dsiexo3. Regular commands include the 
following: 

Commands issued by a command procedure 
Commands received from another subtask 
Commands used to start the hardcopy log at logon 
Commands used as the initial command 
Commands entered as simulated terminal input 
Commands resulting from the message automation table 
Commands entered for an mvs console operator task 
Commands entered from a terminal 
Commands received as hdrtypex messages from an nnt 
Commands queued using the excmd command. 

Before running, all commands are passed to either dsiexoi or dsiexo3. Immediate 
commands are passed to dsiexoi. Regular commands entered from a command 
facility screen are passed to dsiexoi and dsiexo3. The remaining command types 
previously listed are passed to dsiexo3. 



Example of Use: You can use dsiexo3 to restrict usage of particular, regular com- 
mands if your conditions are more complex than those provided by scope 
checking. 

Coding Considerations: None. 

DSIEX04: Log Output 

Description: NetView calls dsiexcw during the logging and tracing process. dsiexo4 
is located within log services and applies to messages logged on the network log, 
the external trace log, the mvs system log, and the hardcopy log. It runs before the 
message is reformatted and sent to the log. dsiexm is not called if dsiexo2a is called 
since logging options may be specified either in dsiexo2A or in the message auto- 
mation table. 

Example of Use: You can use dsiexo4 to edit information sent to the network log, to 
the mvs system log, or to the hardcopy log. You can use dsiexm to send certain 
messages to a specific log or to no log at all. 

Coding Considerations: dsiexo4 can run under any subtask that initiates message 
logging. Be sure that any HLL services you request are supported by the subtask 
under which the routine is running. To determine the subtask you are running 
under see task in "CNMINFC (CNMINFOC) - Query NetView Character 
Information" on page 209. 

Return Code Considerations: DSIEX04 may pass four other return codes in addition 

tO USERASIS, USERDROP, and USERSWAP. 

Return Code Meaning 

userlog Write the message to the network or mvs system log only. 

userlogr Write the substituted message to the network or mvs system log 

only. 

userhcl Write the message to the hardcopy log only. 

userhclr Write the substituted message to the hardcopy log only. 

DSIEX05: Before VTAM Command Invocation 

Description: NetView calls dsiexos when preparing to pass a command to vtam 
through the poi interface; domain qualifiers have been removed and all span 
checking has been completed. 

Example of Use: You can use dsiexos to verify that an operator is authorized to 
issue a particular command. 

Coding Considerations: This exit applies only to commands entered directly, not 
using the 'mvs' prefix, which are passed through NetView's poi. 

Command passed to dsiexos have already been processed under dsiexo3 (and 
perhaps, dsiexoi). 
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DSIEX06: Solicited VTAM Messages 

Description: NetView calls dsiexo6 when it receives a solicited vtam message 
(which is generated in response to a vtam command the user or the ppt issued). 
The message has not yet been processed or logged. 

Example of Use: You can use dsiexo6 to change the message number or text of a 
vtam message or to process vtam messages. 

Coding Considerations: This exit applies only to responses to commands entered 
directly, not using the 'mvs' prefix, which are passed through NetView's poi. 

Message automation is invoked after this exit routine has been called. Therefore, 
any changes made to messages in this user exit may affect message automation. 
Message automation is not invoked for a message that has been deleted by this 
exit routine. 

Messages processed (and not dropped) in DSIEX06 will subsequently be processed 

by DSIEX02A. 

DSIEX07: Cross-Domain Command Send 

Description: NetView calls dsiexoz before commands are sent cross-domain to an 

NNT. 

Example of Use: You can use dsiexo7 to monitor cross-domain traffic through the 
network. 

Coding Considerations: None. 

DSIEX09: Output to the System Console 

Description: NetView calls dsiexo9 when a message is written to the system 
console operator using macro dsiwcs. See dsiwcs in NetView Customization: Using 
Assembler. The message has not been formatted for transmission. 

Example of Use: You can use dsiexo9 to edit messages sent to the system console. 

Coding Considerations: dsiexo9 is called as a result of dsiwcs macro calls. The 
output of the mvs console operator task (ost) is processed by dsiexo2a instead of 

DSIEX09. 

DSIEX10: Input from the System Console 

Description: NetView calls dsiexio when input is received from the system console 
operator. The exit is called after the command has been entered but before it is 
invoked or logged. 

Example of Use: You can use dsiexio to allow the system console operator to 
enter command abbreviations and synonyms. These could then be expanded in 
the user exit routine. 

Coding Considerations: dsiexio can only be called from the main task, not from a 
subtask. 

dsiexio is not called for commands entered by an operator using an mvs console 
operator task (ost). dsiexo3 is called instead. 



1 A MotviAw/ Customization: Usina PLI and C 



DSIEX11: Unsolicited VTAM Messages 

Description: NetView calls dsiexh when an unsolicited vtam message is received 
via the poi interface. In addition, when vtam's ppolog=yes modify or start option is 
used, copies of the messages are presented to dsiexh. This user exit is called 
before the resource name is analyzed and before the message is logged. 

Example of Use: dsiexh can issue cnmsmsg to send a copy of the message buffer 
prior to processing by NetView. 

Coding Considerations: Message automation is invoked after this exit routine has 
been called; therefore, any changes made for messages in this user exit can affect 
message automation. Message automation will not be invoked for a message that 
has been deleted by this exit routine. 

DSIEX12: Logon Validation 

Description: NetView calls DSIEX12 at the completion of the logon process, after the 
logon has been accepted by NetView. 

Example of Use: You can use DSIEX12 to perform additional checking of authori- 
zation and environmental customization. DSIEX12 can also send messages to other 
operators. 

Coding Considerations: If the user exit routine issues a return code of zero, the 
logon proceeds. If specified, your hardcopy log starts and the initial command 
runs. If the issued return code is nonzero, the operator is logged off. 

This exit is called under all ost and nnt tasks including unattended operator and 
mvs console operator tasks. 

The following structure maps the header information in the cmdbuf (Cmdbuf) 
passed to the DSIEX12 exit, offset and length values are given in bytes. 



OFFSET 


LENGTH 


FUNCTION 





8 


OPERATOR ID NAME 


8 


8 


OPERATOR LU NAME 


12 


8 


PASSWORD 


20 


8 


HARDCOPY DEVICE NAME 


28 


8 


PROFILE NAME 


36 


8 


NEW PASSWORD 



DSIEX13: OST/NNT Message Receiver 

Description: NetView calls DSIEX13 when either a message buffer or a user-defined 
internal function request (ifrcodus) is received through macro dsimqs. dsiex-13 is 
called within the message receiver for subtask-to-subtask communication. A 
message buffer is any non-HDRTYPEi (ifr) buffer. See ifrcodus and dsimqs in 
NetView Customization: Using Assembler. 

Example of Use: You can use DSIEX13 in conjunction with ifrcodus to initiate a user 
function with a buffer. Code DSIEX13 to perform the user function specified by 

IFRCODUS. 

Coding Considerations: When DSIEX13 returns, these buffers are written to the 
operator terminal unless return code userdrop is issued. The messages are 
logged after user exit dsiexo2a is called. 
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DSIEX14: Before Logoff 

Description: NetView calls dsiexh when an ost or nnt subtask is preparing to end 
for any of these reasons: 

• If logoff is entered at the operator's terminal 

• If the subtask losterm exit is driven (vtam) 

• If the subtask is posted to terminate. 

The subtask cannot communicate with the operator's terminal at this point. It is 
possible, however, to write to the system console and to write entries to the log. 

Example of Use: You can use dsiexh to save accounting information or update 
tables. 

Coding Considerations: Because there is no buffer associated with logoff proc- 
essing, dsiexh does not receive an input buffer (the length of the command buffer 
will be zero). 

Return Code Considerations: NetView ignores any return code received from this 
user exit routine. 

DSIEX16: Post-Message Automation Table Exit 

Available through an assembler interface only. See NetView Customization: Using 
Assembler. 

XITBN: BSAM Empty File 

Description: The dst calls xitbn if the dst encounters a bsam open failure because 
of an empty data set or file. 

Example of Use: You can use xitbn to place a record in the empty data set. You 
should code this user exit only if you wish to write your own bsam subtask using dst 
as a base. 

Coding Considerations: xitbn can only use the service facilities available to the 
dst subtask. 

Return Code Considerations: To initialize the bsam data set or file, return the 
userswap return code and set the command buffer to the record to be used. A 
return code other than userswap causes the dst to end. 

XITBO: BSAM Output 

Description: The dst calls xitbo immediately before the record is written to the 
bsam data base. 

Example of Use: You can use xitbo to modify the record before it is sent to the 
bsam data set or file. 

Coding Considerations: xitbo can only use the service facilities available to the 
dst subtask. 

You should avoid coding user exits for frequently executed functions, such as bsam 
i/o, since performance can be degraded significantly. 
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XITCI: CNM Interface Input 

Description: The dst calls xitci after cnm data is received. 

Example of Use: You can use xitci to modify cnm interface input data (Deliver ru). 

Coding Considerations: xitci can only use the service facilities available to the dst 
subtask. 

If a substitute buffer is returned, the data must be a valid sna request unit (ru). See 
Systems Network Architecture Product Formats for a discussion of ru formats. 

xitci invoked under the dsicrtr subtask allows access to unsolicited cnm data prior 
to NetView routing (except for cross domain alerts, which are only accessible 
under the bnjdserv subtask). xitci invoked under a dst other than dsicrtr will allow 
access to unsolicited cnm data particular to the invoking dst. 

Network Services Request Units are routed as follows: 



Request 


Header Value 


Responsible Subtask Name 


RECMS 


X'010381' 


BNJDSERV 


RECFMS 


X'410384' 


bnjdserv and AAUTSKLP 


ROUTE-INOP 


X'410289' 


AAUTSKLP 


CNM 


X'810814' 


AAUTSKLP 


NMVT 


X'41038D' 





nmvt Request Units are routed based upon the Major Vector Key: • 

Major Vector Key Responsible Subtask Name 

X'0000' BNJDSERV 

X'0001 ' BNJDSERV 

X'0010' AAUTSKLP 

X'0025' BNJDSERV 

X'006F' DSIGDS 

X'0080' AAUTSKLP 

X'13FF' BNJDSERV 

If the data is a cross domain alert, the first 44 bytes of the data are mapped by the 
Focal Point Transfer ru (see NetView Customization: Using Assembler for a com- 
plete mapping) and the remainder of the data is the actual nmvt. The first two 
bytes of the Focal Point Transfer ru contain the length of the entire buffer (fpt ru + 
nmvt). The next two bytes contain the header id which is always X'1040'. The 16th 
byte contains the length of the originating domain id and the 17th through 24th 
bytes contain the actual originating domain id. When returning a substitute buffer 
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do not modify the Focal Point Transfer ru (the first 44 bytes); replace only the nmvt 
portion of the buffer (it must be replaced with a valid nmvt). 

XITCO: CNM Interface Output 

Description: The dst calls xitco prior to a request for cnm interface output. 

Example of Use: You can use xitco to modify the request for cnm data (Forward 

RU). 

Coding Considerations: xitco can use only the service facilities available to the 
dst subtask. 

If a substitute buffer is returned, the data must be a valid sna request unit (ru). See 
Systems Network Architecture Technical Overview for a discussion of ru formats. 

XITDI: Data Services Task (DST) Initialization 

Description: The dst calls xitdi for each statement read by the dst during initializa- 
tion. When end-of-file is reached, this user exit is entered and the length of the 
input command buffer is zero. You can code up to 10 module names for each user- 
written exit routine. See Chapter 3 on page 21 for more information on xitdi 
during dst initialization. 

Example of Use: You can add xitdi to the dst initialization deck to provide user 
initialization values to dst initialization. 

Coding Considerations: Do not replace NetView provided dst xitdi exits. 

xitdi can use only the service facilities available to the dst subtask. 

Note: If all initialization data is to be processed by xitdi, specify the dst initializa- 
tion statement that identifies xitdi as the first statement in the dst initialization 
member. 

Return Code Considerations: xitdi can prevent the dst from processing a defi- 
nition statement by passing return code userdrop. 

When called for an end-of-file situation, a nonzero return code indicates that the 
dst should be stopped. 

XITVI: VSAM Input 

Description: The dst calls xrrvi after a cnmkio call for input is issued. The record 
has been read from the vsam data base, but it is not yet passed to the requesting 
data services command processor. 

Example of Use: You can use xitvi to modify the record after it has been retrieved 
from a vsam data set or file. 

Coding Considerations: xitvi can only use the service facilities available to the dst 
subtask. 

You should avoid coding user exits for frequently executed functions, such as vsam 
i/o, since performance can be degraded significantly. 
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XITVN: VSAM Empty File 

Description: The dst calls xitvn if the dst encounters a vsam open failure because 
of an empty data set or file. 

Example of Use: You can use xitvn to place a record in the empty data set. 
NetView provides its own xitvn for vsam logs generated under dst. You should 
code this user exit only if you wish to write your own vsam subtask using dst as a 
base. 

Coding Considerations: xitvn can only use the service facilities available to the 
dst subtask. 

Notes: 

1. Only vsam key-sequenced data sets (ksds) are supported. 

2. Do not replace NetView provided xitvn exits for the dsilog and dsitrace sub- 
tasks. 

Return Code Considerations: To initialize the vsam data set or file, return the 
userswap return code and set the command buffer to the record to be used. A 
return code other than userswap causes the dst to end. 

XITVO: VSAM Output 

Description: The dst calls xitvo immediately before the record is written to the 
vsam data base via the cnmkio service. 

Example of Use: You can use xitvo to modify the record before it is sent to the 
vsam data set or file. 

Coding Considerations: xitvo can use only the service facilities available to the 
dst subtask. The text portion is mapped by dsilogds when using this exit for the 
dsilog task. 

You should avoid coding user exits for frequently executed functions, such as vsam 
i/o, since performance can be degraded significantly. 

XITXL: External Logging 

Description: The dst calls xitxl whenever data is to be sent to an external log 
using cnmsmsg with the extlog parameter. For example, session monitor performs 
external logging of response time and configuration data. 

Example of Use: Write user defined data to a user defined log. 

Coding Considerations: xitxl can use only the service facilities available to the 
dst subtask. 

The following offsets (in byte values) can be used to access the cmdbuf (Cmdbuf). 
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OFFSET 


LENGTH 


NAME 


FUNCTION 





2 


ELBLEN6 


Unsigned length of 
header 


2 


2 


ELBRLENG 


Unsigned length of 
record 


4 


1 


ELBTYPE 


Log type 


5 


3 


ELBLOG 


EBCDIC log type 


8 


4 




Reserved by NetView 


12 






Start of record 
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Chapter 3. HLL Data Services Command Processors 

hll command processors that use the cnmcnmi and cnmkio services must run under 
a Data Services Task (dst). The dst provides the underlying interfaces required by 
both cnmcnmi and cnmkio. 

A Data Services Task (dst) is a set of NetView interfaces built on top of the NetView 
optional task base. The NetView optional task is discussed in NetView 
Customization: Using Assembler. A dst provides a subtask processing module 
(dsizdst) along with the following: 

• An initialization exit interface 

• A Data Services Command Processor (dscp) interface that provides support for 
vsam (via cnmkio) and cnmi (via cnmcnmi). 

• Various user exit interfaces, (see Table 1 on page 11) 

Note: For further information on the task and dstinit statements referenced in this 
chapter see NetView Administration Reference. 

Data Services Task Installation 

A task statement for the dst subtask must be coded in the dsidmn member of the 
dsiparm data set. The task statement has the following format: 

TASK MOD=DSIZDST,TSKID=taskname,MEM=usennem,PRI=n s INIT=Y|N 

• mod keyword - Must specify dsizdst as the subtask processing module, dsizdst 
is provided by NetView and provides the necessary initialization, processing, 
and termination routines to use the dscp interfaces. 

• tskid keyword - The task name. Each task in NetView must have a unique task 
name. 

• mem keyword - Specifies the user-defined initialization member found in 
dsiparm to be used by this task. The initialization dataset member must 
contain dstinit statements to provide various initialization parameters required 
by dsizdst. The statements will be discussed under their respective interfaces. 
User-defined statements can also be processed by the initialization exit. 

• pri keyword - Specifies the relative task priority (1-9). 1 is the highest task pri- 
ority that can be assigned, and 9 is the lowest. 

• init keyword - Specifies whether the task is to be started during NetView initial- 
ization (init=y) or through the start command only (init=n). 



Initialization 



When the dst is started the initialization data set specified by the mem keyword on 
the task statement is read, and the dstinit statements are processed. 

• dstinit Keywords - Related to initialization. 

- funct - Specifies which dst services will be required. In all cases, the 
ability to call hll dscps is provided. The function choices are: 

— other - The dst does not require the cnmi or vsam interfaces. 
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— both - Both the vsam and cnmi interfaces are required. 

— cnmi - Only the cnmi interface is required. 

— vsam - Only the vsam interface is required. 

— xitdi keyword - Specifies the name of the user provided initialization exit. 
The exit is called with the standard NetView user exit interface as docu- 
mented in Chapter 2 on page 9 and is called once for every statement in 
the specified initialization member (mem keyword of task statement). When 
End-Of-File has been reached, the length of cmdbuf {Cmdbuf) will be zero. 
For each statement (except End-Of-File condition), the standard user exit 
return codes will cause the following actions: 

USERASIS (0) The statement will be processed by the NetView dst 
module (dsizdst). If it is not a valid dstinit statement, 
dsizdst will reject it with an error message and con- 
tinue processing. 

USERDROP (4) The statement will not be processed by dsizdst. This 
return code should be used if your user exit is going to 
process the statement (you can define your own initial- 
ization statements). 

USERSWAP (8) The swapped buffer will be processed by dsizdst. If the 
swapped buffer does not contain a valid dstinit state- 
ment, it will be rejected by dsizdst and processing will 
continue. 

When returning from the last call (for End-Of-File), any non-zero return 
code will terminate the dst. This should only be done if the initializa- 
tion process has failed. 

Data Services Command Processors 

Command processors that run under dsts are called data services command 
processors. They must be defined as type = d (dst only) or type=rd (Regular or 
dst). The following services are available to data services command processors 
(dscp). 

CNM Data Services 

An appl definition with auth=cnm must be defined to vtam for the dst (use the tskid 
name as the appl name). The dst provides access to both solicited and unsolicited 
cnm data, cnmcnmi can be issued to solicit cnm data from the Network. An hll dscp 
can be defined to receive unsolicited cnm data from vtam. 

• Unsolicited cnm Data Interface 

vtam provides a default table (istmgcoi) that controls the routing of unsolicited 
cnm rus. You can write a supplemental table (istmgcoo) to override the default 
routing information provided by vtam. The routing information consists of a 
particular ru type and the name of an application which is to receive the partic- 
ular type of data. When a dst is defined with cnmi services, an acb is opened 
with an acb name (the application name) equivalent to the task name as 
defined by the tskid parameter in the dst task definition statement (the one 
exception is Hardware Monitor whose cnmi dsts task name is bnjdserv, but the 
application name is bnjhwmon). If the dst task name is entered as the applica- 
tion name in the vtam routing table, the unsolicited data RU will be passed to 
the unsolicited data services command processor for that dst. 
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- dstinit Keywords - Related to unsolicited cnm data interlace. 

— unsol - Specifies the command verb name of the module that is to 
serve as the unsolicited dscp for this dst. The unsolicited dscp should 
not issue the cnmcnmi macro, but may Issue the cnmkio macro. 

— dsrbu - Specifies the number of unsolicited Data Services Request 
Blocks (dsrbs) which are to be allocated to this dst. If unsolicited cnm 
data is not going to be processed by this dst, then this value should be 
set to zero; otherwise it should be set to one. 

- hll dscp Interface 

When the unsolicited hll dscp receives control, cnmdbuf (Cmdbuf) will 
contain the unsolicited data ru. 

• Solicited cnm Data Interface 

cnmcnmi can be used by an hll dscp to acquire Communications Network Man- 
agement data from the network. 

- dstinit Keywords - Related to the solicited cnm Data Interface. 

— dsrbo - Specifies the number of solicited dsrbs that will be required by 
this task and limits the number of concurrent cnmcnmi and/or cnmkio 
requests. This value must be at least 1 (a dscp will not be called 
unless a solicited dsrb is available) and no greater than 862. 

VSAM Services 

The cnmkio service routine can be invoked by a dscp to perform i/o for a specified 
vsam data set. 

• dstinit Keywords - Related to cnmkio service routine. 

- dsrbo - Specifies the number of solicited dsrbs that will be required by this 
task and limits the number of concurrent cnmcnmi and/or cnmkio service 
routine. This value must be at least 1 and no greater than 862, (a dscp will 
not be called unless a solicited dsrb is available). 

- pddnm - Specifies the dd name of the primary data set to be used by vsam 
services. 

- ppass - Specifies the vsam password to be used when the primary data set 
acb is opened. 

- sddnm - Specifies the dd name of the secondary data set to be used by 
vsam services. The NetView switch command is used to control which data 
set is currently the active data set. 

- spass - Specifies the vsam password to be used when the secondary data 
set acb is opened. 

- macrf - Specifies local resource sharing. 

- xitvn - Specifies a user exit to receive control when an empty vsam data set 
has been opened for processing. This exit allows you to put an initializa- 
tion record into the data set. 

- xitvi - Specifies a user exit to receive control upon input from the vsam data 
set before the input record is passed to the requesting scp. 

- xiTvo - Specifies a user exit to receive control before output of a record to 
the vsam data set. 
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User Defined Services 

hll command processors defined as type=d or type=rd can be invoked under the 
dst to perform user defined functions in addition to cnmkio or cnmcnmi functions. 

Scheduling Commands Under the DST 

The cnmsmsg service routine can be used to schedule a dscp and, in conjunction 
with the wait command, can wait for the dscp to send back the results of the sched- 
uled work. For samples of data services, command processors, and user exit rou- 
tines, see Appendix B on page 263 for pl/i, and Appendix on page 295 for c. 
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Chapter 4. Coding Your PL/I Program - Interfaces and 
Restrictions 

This chapter provides necessary information for coding hll command processors 
and user exits in pl/i. The appropriate interfaces and language dependent 
restrictions are discussed. 

Initial Parameters 

Three parameters are passed to an hll program upon invocation. Chapter 5 con- 
tains a sample template for coding the main procedure statement and the initial 
parameter declarations in pl/i. The descriptions of the initial parameters are as 
follows: 

HLBPTR 

A 4-byte pointer field containing the address of the hlb control block (dsiphlb). 
The hlb control block is the hll api interface block that is used to communicate 
between the hll service routines and hll programs in the NetView environ- 
ment. This pointer is required on all hll service routine invocations. 

CMDBUF 

A varying length character string that contains the command or message that 
drove this program. 

If this program was driven as a user exit (other than dsiexo2A), this string con- 
tains the message that drove this exit. If driven as dsiexo2A, cmdbuf will not 
contain any useful information. The user will have to retrieve the message 
from the Initial Data Queue (idataq). 

ORIGBLCK 

A 40-byte structure that describes the origin of the request that caused exe- 
cution of this program, origblck is mapped by dsiporig. 

HLL Run-Time Options 

hll run-time options can be specified by declaring and initializing the external vari- 
able named hllopts. If the user does not code hll run-time options, the default hll 
run time options are assumed. The default value for hllopts is zero. The following 
bits are defined in hllopts: 
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Bit 
Position 





Field Name 

HLL QUEUED INPUT 



HLL NO CANCEL 



2-31 



Description 

Determines if an hll program will accept 
queuecI input. Refer to the queue command 
in the NetView Operation manual for further 
detail. 

= hll program will NOT accept QUEUEd 
input 

1 = hll program will accept QUEUEd input 
Determines if an hll program will terminate 
on cancel/reset. Refer to reset command 
in the NetView Operation manual for further 
detail. 

= Cancellable 

1 = Non-cancellable 

reserved for internal use. Do not assign 
any values to these fields. 



The following example illustrates how the default hll run-time options can be over- 
ridden in an hll program written in pl/i. In this case, the user has chosen to make 
this pl/i program non-cancellable. 

DCL HLLOPTS BIT (32) STATIC EXTERNAL 

INIT(' 01000900000000000000000000000000' B); 



PL/I Run-time Options 



pl/i run-time options can be specified by declaring and initializing the external vari- 
ables named pliopts, isasiz and heapsiz. If the user does not code pl/i run-time 
options, the default pl/i run-time options are assumed. Values for the pl/i run-time 
options are displayed on the entry screen (hapientr) into your pl/i program 
(id=plientry) when monitoring execution of your program using the Remote Inter- 
active Debugger (RID). This is explained in detail in Chapter 11 on page 167. 

Run-time options are passed to pl/i using the plicallb entry point conventions. 
Refer to the PL/I Programming Guide for a detailed description of each option. The 
following bits are defined in pliopts. 
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Bit 




Position 


Field Name 





REPORT 


1 


NOREPORT 


2 


SPIE 


3 


NOSPIE 


4 


STAE 


5 


NOSTAE 


6 


COUNT 


7 


NOCOUNT 


8 


FLOW 


9 


NOFLOW 


10 


KEEPHEAP 


11 


FREEHEAP 


12 


ANYHEAP 


13 


BELHEAP 


14-31 


Map to the bits 




defined for plicallb 




entry point con- 




ventions. 



pl/i programs must run with the nostae and nospie options when running in the 
NetView environment. Running with the stae or spie options will cause unpredict- 
able results in cases where error recovery is necessary. The following example 
illustrates how the default pl/i run-time options (pliopts) can be overridden in an 
hll program written in pl/i. In this case, the user has chosen to run this program 
with the report option on. Note that the other pl/i run-time options defined in 
pliopts (nostae, nospie, etc.) are still specified. 

DCL PLIOPTS BIT(32) STATIC EXTERNAL 

INIT ('1001010101 1010900000000000000000' B) ; 

External variables isasiz and heapsiz correlate to the isasize and HEAP(s/ze param- 
eter) run-time options discussed in the PUI Programming Guide. The default 
values for isasiz (4000) and heapsiz (512) are obtained from the NetView Constants 
Module (CNMS0055). These values can be tailored for your environment. Refer to 
the NetView Installation and Administration Guide for details on how to change the 
default values in the constants module. 

The following example illustrates how the default values for isasiz and heapsiz can 
be overridden in the user's program. 

DCL (ISASIZ INIT(4096), /* Override ISA size */ 

HEAPSIZ INIT(256)) /* Override HEAP size */ 

STATIC EXTERNAL FIXED BIN(31); 

To achieve optimum performance, it is recommended to run with the report option 
until accurate isa and heap sizes are determined. Refer to the run-time storage 
section of the PL/I Programming Guide for further details. 



Chapter 4. Coding Your PL/I Program - Interfaces and Restrictions 29 



Parameters Passed to HLL Service Routines 

There are four different types of parameters that can be passed to hll service rou- 
tines. Each of the parameters described throughout Chapter 12 fall into one of 
these categories: 

• Pointer Variables 

• Integer Variables 

• Fixed Length Character Strings 

• Varying Length Character Strings 

A discussion of each of these parameter types follows. This section describes how 
each of these parameter types can be declared, initialized and passed to the hll 
service routines. Examples and recommendations for writing hll programs in pl/i 
have been provided in this chapter. Note that these examples are not complete. 
They have been included here to emphasize how the hll service routine parame- 
ters should be declared, initialized and passed. For complete examples of user 
written hll programs, see the hll samples shipped with NetView. Refer to 
Appendix B on page 263. 

Pointer Variables 

A pointer variable is a 4-byte pointer field containing an address. All hll service 
routines require at least one argument of this type, hlbptr. hlbptr is required for 
all hll service routine invocations. The value of hlbptr is calculated by NetView 
and passed to the hll command processor or user exit. Therefore, it only needs to 
be declared in pl/i. The user should NEVER assign a value to this variable. This is 
the only parameter of this type which does not have to be assigned by the user. 

Note: The user does not need to specify the hlbptr parameter when coding the 
hll service routine invocation in the pl/i macro format. When an hll service 
routine is invoked using the pl/i macro format, hlbptr is inserted for the user before 
the hll service routine is actually invoked. 

If an hll service routine is expecting an address in a pointer field, the user is 
responsible for assigning a value to that pointer field before invoking the hll 
service routine, hlbptr is the only exception to this rule. In pl/i, it is advised to use 
the addr function when passing pointer variables to hll service routines rather 
than creating a separate pointer variable for this purpose. This will ensure that the 
pointer variable has been assigned a value before invoking the hll service routine. 
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DCL VARTOVAR CHAR(8) INIT('VARTOVAR'); /* VARTOVAR constant 



7 



DCL HLBPTR PTR 
DCL SRCPTR PTR 
DCL DSTPTR PTR 



/* HLB pointer MUST BE DECLARED! */ 



/* Source pointer 

/* Destination pointer 



DCL DSTLEN FIXED BINARY(31,0) ; /* Length of Destination 



DCL SRCBUF CHAR(255) VARYING; 
DCL DSTBUF CHAR(255) VARYING; 

SRCPTR = ADDR(SRCBUF); 
DSTPTR = ADDR (DSTBUF); 

DSTLEN = LENGTH (DSTBUF); 
SRCBUF = (255)'A'; 
DSTBUF = (255)' '; 



/* Source buffer 

/* Destination buffer 



*/ 
*/ 

7 

V 
V 



/* Address of source buffer */ 

/* Address of destination buffer */ 

/* Length of destination buffer */ 
/* Initialize source buffer */ 

/* Initialize destination buffer */ 



IS CALL CNMCPYS (HLBPTR, SRCPTR, DSTPTR, DSTLEN, VARTOVAR); /* Copy buffer*/ 
Figure 1. Using Pointer Variables in PL/I 



hlbptr is declared as a pointer (ptr) variable to be used in the cnmcpys invoca- 
tion. The user did not assign a value to hlbptr. hlbptr is specified for this 
invocation because the user has chosen to invoke cnmcpys using the pl/i call 
format rather than the pl/i macro format of the invocation. Chapter 12 contains 
examples of how to invoke hll service routines using the pl/i macro format. 

srcptr is declared as a pointer (ptr) variable. 



srcptr is assigned the address of the source buffer (srcbuf) to be used in the 
cnmcpys invocation. 



Both hlbptr and srcptr have been passed as parameters to cnmcpys. 

Replacing IS with the following step illustrates the use of the addr function in 
pl/i. Using the addr function eliminates the need to declare pointer (ptr) vari- 
ables and is advisable whenever possible. Note the use of a character con- 
stant instead of the vartovar variable. 

CALL CNMCPYS (HLBPTR, ADDR(SRCBUF) ,ADDR(DSTBUF) , DSTLEN, 'VARTOVAR' ) ; 

Note: If the addr function is used to represent a pointer to a varying length char- 
acter string, warning message ielo548I will be generated at compile time. 
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Integer Variables 



Several of the hll service routines require the user to pass a 4-byte integer value 
to be used as a length, count, queue number, etc.. Figure 2 illustrates the use of 
integer variables in the pl/i environment. 



DCL HLBPTR PTR; /* HLB pointer MUST BE DECLARED! 

DCL SPNAME CHAR(8) VARYING INITCPOOLNAME'); /* Subpool name 



DCL SPFUNC CHAR(8); 
DCL SPTOKEN FIXED BIN (31,0) 
DCL SPLENG FIXED BIN(31,0) 
DCL SPPRICNT FIXED BIN(31,0) 
DCL SPSECCNT FIXED BIN (31,0) 
DCL SPCLASS FIXED BIN(31,0) 

SPFUNC = 'ALLOC; 
SPTOKEN = 0; 
SPLENG = 256; 
SPPRICNT = 3; 
SPSECCNT = 2; 
SPCLASS = 1: 



/* 
/* 
/* 
/* 
/* 
/* 

/* 
/* 

/* 
/* 
/* 
/* 



Subpool function 

Subpool token (returned) 

Cell size 

Number of cells in primary 

Number of cells in secondary 

Class of storage 

Function is ALLOCATE 
Initialize subpool token 
Cell size = 256 bytes 
Primary count = 3 
Secondary count = 2 
Class = 31 bit addressable 



7 
7 
7 
7 
7 
7 
7 
7 

7 
7 
7 
7 
7 
7 



111 CALL CNMP00L(HLBPTR, SPFUNC, SPTOKEN, SPNAME, SPLENG, SPPRICNT, SPSECCNT, 
SPCLASS); /* Allocate subpool */ 

Figure 2. Using Integer Variables in PL/I 



sptoken is declared as a 4-byte integer (FIXED BIN(31,0)). 

spleng is declared as a 4-byte integer (FIXED BIN(31,0)). 

sptoken is initialized to zero. A value will be returned in sptoken upon suc- 
cessful completion of the cnmpool invocation. 

spleng is assigned a value of 256 to be used in the call to cnmpool. 

sptoken and spleng have been passed to cnmpool. The value of sptoken will 
be returned to the user upon successful completion of the call to cnmpool. 
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Fixed Length Character Strings 

The majority of the hll service routines require the user to pass one or more fixed 
length character strings as arguments. Most of these fixed length character 
strings, except adorigin and gdorigin, are eight characters long. These exceptions 
are discussed below. 

pl/i constants for most of the fixed length character strings have been provided in 
dsipcons. dsipcons is optional and can be tailored to the specific needs of the user. 
The following steps correlate to the steps outlined in Figure 2. 

I 

spfunc is declared as an 8-byte character field (CHAR(8)). 

i 

Character string 'alloc' is assigned to spfunc to be used in the call to cnmpool. 

El 

spfunc is passed to cnmpool. spfunc could have been initialized (see vartovar 
in Figure 1 step Q ) or passed to cnmpool as a character constant as shown 
here. In all cases, it is important to note that pl/i automatically pads fixed 
length character fields with blanks. 

CALL CNMPOOL (HLBPTR, 'ALLOC ,SPT0KEN, SPNAME, SPLENG.SPPRICNT.SPSECCNT, 
SPCLASS); /* Allocate subpool */ 

The only fixed length character fields required for hll services that are not 8 bytes 
in length are origin blocks. The mapping structure for an origin block resides in 
file dsiporig which is included by dsipli. There are two types of origin blocks used 
by the hll service routines. 

The first type of origin block (origblck) is a 40-byte structure which must be 
declared by the user. This is a required initial parameter which was previously 
described in the 'Initial Parameter' section of this chapter. The user is responsible 
for declaring this 40-byte structure but should never need to alter it. Refer to the 
pl/i coding template in Chapter 5 on page 37 for an example of how to declare 
origblck. 

The second type of origin block {adorigin, gdorigin) is specified by the user. 
adorigin and gdorigin must be at least 38 bytes long and must map to the first 38 
bytes of the origin block structure (dsiporig). The user MUST declare these origin 
blocks separately from the origin block which is required as an initial parameter. 
The initial parameter origin block (origblck) should NOT be used in place of 
adorigin or gdorigin. 

Varying Length Character Strings 

, Several of the hll service routines require the user to pass a varying length char- 
acter string as an argument. The following steps correlate to the steps outlined in 
Figure 2 on page 32. 

spname is declared as a varying length character field with a maximum length 
of 8 bytes (char(8) varying), spname is also initialized in this step. 



spname is passed to cnmpool. 
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Control Blocks and Include Files 

There are a number of control blocks and include files that are required for exe- 
cution of an hll program (written in pl/i) in the NetView environment, dsipli is the 
main file that includes the rest of the files and is necessary to compile hll pro- 
grams written in pl/i. Optional include files have been provided to assist the user 
in coding and maintaining hll programs, dsipli, dsipcnm and dsipcons may be tai- 
lored to the user's needs. 

Note: Tailoring files can lead to better performance in many cases. This is espe- 
cially helpful in performance sensitive environments such as the user exit environ- 
ment. 

Appendix A on page 245 contains the following list of control blocks and include 
files: 

DSIPLI (Required) Must be included by all hll programs written in pl/i. 

dsipli includes all of the external hll control blocks and include 
files needed to compile and run pl/i programs in the NetView 
environment. Refer to the pl/i coding template in Chapter 5 on 
page 37 for usage. 

DSIPCNM (Optional) Declares hll return code constants for pl/i. 

DSIPCONS (Optional) Declares constants that are helpful when coding 

High-Level Language programs in pl/i. 

DSIPHLB (Required) pl/i mapping of internal control block dsihlb. 

DSIPHLLS (Required) pl/i definitions for hll service routines. 

DSIPORIG (Required) pl/i mapping of the origin block of the request that 

caused the execution of the program currently running. 

PL/I I/O Considerations 

pl/i provides several input and output statements that allow the user to transmit 
data between main storage and auxiliary storage of a computer, pl/i programs uti- 
lizing such file i/o capabilities will run in the NetView environment. However, there 
are some important things to consider when doing file i/o in pl/i. 

Each file referenced from your pl/i program correlates to a physical data set in 
auxiliary storage. Before opening a file for i/o, the user must ensure that the 
appropriate data set has been allocated. Allocation can be performed under tso or 
by using the NetView allocate command described in NetView Operation. 
NetView also provides a free command to deallocate a data set. 

If the data set is allocated from tso, the user must also add a corresponding data 
definition (dd) statement to the NetView start up procedure. The data definition 
name {ddname) must match the name of the pl/i file. The dd statement specifies a 
physical data set name (dsname) and gives its characteristics: 

//OUTFILE DD DSN=MYPR0G.0U7FILE, ... 

A dd statement is not necessary if the data set is allocated using the NetView allo- 
cate command. 

The following example illustrates the use of file i/o in an hll program written in pl/i. 
Note the use of the on undefinedfile statement to protect against an open failure. 
Check for this condition before opening a file for i/o. 
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DCL OUTFILE FILE STREAM; /* Declare output file 



/***********************************************^ 

/* Check for error before opening file for I/O. If UNDEFINEDFILE */ 
/* condition is raised, issue an error message end exit program. */ 

ON UNDEFINEDFILE(OUTFILE) 
BEGIN; 

CALL CNMSMSG(HLBPTR, ' OUTPUT FILE IS UNDEFINED' ,'MSG' ,'OPER' ,"); 

HLBRC = CNM_G00D; 

STOP; 
END; 

OPEN FILE(OUTFILE) OUTPUT; /* Open file for output */ 



PUT SKIP FILE (OUTFILE) ... /* Write to output file */ 

CLOSE FILE(OUTFILE); /* Close output file */ 

If the user chooses to write to a common output file from two or more pl/i pro- 
grams, access to the common file must be coordinated by the programs. This can 
be accomplished using NetView's cnmlk routine if desired. If access is not coordi- 
nated, the user may experience a system abend 213. 

Special care should be taken when attempting to share open files between two or 
more hll programs. Sharing of open files must be coordinated between the 
sharing programs, pl/i and c cannot share an open file. However, a c program can 
read a file created by pl/i. 

If the user chooses to code a get or put statement without the file option, the com- 
piler will insert the file names sysin and sysprint. By default, sysin and sysprint 
are directed to the terminal. These defaults are not valid and will cause undeter- 
mined results if used in the NetView environment. Terminal i/o can be done using 
wait for opinput and cnmsmsg as described in Chapter 12. 

Refer to PL/I Programming: Language Reference and PL/I Programming Guide for 
a more detailed discussion on files and pl/i i/o. 

PL/I Run-Time Considerations 

All errors detected at run-time are associated with pl/i conditions that can be 
handled by ON-units written by the programmer. An ON-unit is a user written state- 
ment that establishes an action to be executed when a particular pl/i error condi- 
tion is raised, pl/i error conditions can be detected by the operating system or by 
pl/i. If a pl/i program is running with the nostae or nospie options, only the condi- 
tions detected by pl/i can be handled by ON-units. Since pl/i programs running in 
the NetView environment must run with the nostae and nospie options, the user will 
not be able to code ON-units for operating system detected conditions. While 
debugging a pl/i program in the NetView environment, it is allowable to run with 
the stae and spie options until the run-time problems have been resolved. Most 
run-time errors are represented by diagnostic messages written to the sysprint file. 
See PL/I Programming Guide for a complete discussion on error and condition 
handling. 
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Considerations for HLL Command Processors 

It is necessary to code a cmdmdl statement in dsicmd for each hll command 
processor that you have written, cmdmdl type will be dependent on the functions 
that your command processor performs. Keep in mind that some of the hll ser- 
vices are only useful when executed under a Data Services Task (dst). There is no 
support for hll command processors running as immediate commands (type=i). 
The cmdmdl statement is described in NetView Administration Reference. 

Return Codes 

Upon completion of an hll service routine, the completion code from that service 
routine is stored in the return code field (hlbrc) of the hlb control block. This field 
should be checked after each hll service routine invocation. It is recommended 
that this field be utilized when passing return codes between hll programs. 

For a complete list of hll api return codes, see dsipcnm in Appendix A. Refer to 
Chapter 12 for a list of return codes that apply to each hll service routine. 

pliretv and pliretc should not be used when passing return codes between hll 
programs written in pl/i. Both of these routines could yield unpredictable results in 
the NetView environment. Normal termination of a pl/i program can be achieved 
by assigning a value to hlbrc and issuing a return statement as shown here. 

HLBRC = CNM_G00D; /* Successful completion */ 

RETURN; /* Return to caller */ 

Restrictions for HLL Programs Written in PL/I 

The following commands should not be used when coding pl/i programs to run in 
the NetView environment: 

DISPLAY Use NetView' s CNMSMSG service routine. 

WAIT, DELAY Use NetView' s WAIT command. 

ON FIXEDOVERFLOW These condition codes will not work 

ON OVERFLOW in NetView since they require SPIE 

ON UNDERFLOW and STAE. 
ON ZERODIVIDE 

PLIRETV Return codes should be passed via 

PLIRETC HLBRC. 



36 NetView Customization: Using PLI and C 



Chapter 5. PL/I High-Level Language Services 

This chapter is an example-oriented discussion of commands and services pro- 
vided by NetView in support of pl/i. The complete syntax and usage of each 
command and service routine can be found in Chapter 12. 

Note: When you are compiling pl/i programs you will receive a warning message 
IEL0548I. This message should be ignored. 

PL/I Sample Template 

The following is a coding template sample to be used when coding hll programs in 
pl/i. This template can be used, with your enhancements, to utilize NetView func- 
tions and commands. Further examples in this chapter should be used in conjunc- 
tion with this template. 

PTMPPLT: PROC(HLBPTR,CMDBUF,ORIGBLCK) OPTIONS (MAIN, REENTRANT); 

y***************************************************************** 

/* */ 

/* (C) COPYRIGHT IBM CORP. 1989 */ 

/* 7 

/* IEBCOPY SELECT MEMBER=( (CNMS4200, PTMPPLT, R)) */ 

/* V 

/* (Explanations included in parentheses should be deleted) */ 
/* (after the pertinent information has been filled in. ) */ 

/* V 

/* Descriptive Name: High-Level Language PL/I Template */ 
/* (This is the more descriptive name or title of the module.) */ 

/* V 

/* Function: */ 

/* Template for writing HLL modules in PL/I. */ 

/* (This is the description of what the module does.) */ 

/* (It may be paragraph or pseudocode form. ) */ 

/* */ 

/* Dependencies: */ 

/* (List conditions that must be met in order for this) */ 

/* (module to perform. An example of this might be a ) */ 

/* (key data area that must already have been built. ) */ 

/* V 
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/* Restrictions: */ 

/* (List any limitations this module may have.) */ 

/* V 

/* Language: PL/I */ 

/* V 

/* Input: */ 

/* 1) A pointer to a 4-byte field containing the address of */ 

/* the HLB control block. */ 

/* 2) A varying length character string containing the */ 

/* command or message which invoked this program. */ 

/* If this program was invoked as a command processor, */ 

/* this will be a command string. */ 

/* If this program was invoked as a user exit (other than */ 

/* DSIEX02A), this will be a message string. When driven */ 

/* as DSIEX02A, this string will be empty and the message */ 

/* must be retrieved from the Initial Data Queue (IDATAQ). */ 

/* 3) A 40-byte structure which describes the origin of the */ 

/* request that caused execution of this program. */ 

/* V 

/* Output: */ 

/* (Describe any output from this module.) */ 

/* */ 

/* Return Codes: returned in Hlbrc */ 

/* For Command Processors: */ 

/* = normal exit */ 

/* -5 = cancelled */ 

/* (List any other return codes meaningful to this module.) */ 

/* For User Exits: */ 

/* = USERASIS (Leave the contents of the message buffer */ 

/* unchanged) */ 

/* 4 = USERDROP (Drop the message buffer) */ 

/* 8 = USERSWAP (Change the contents of the message buffer) */ 

/* */ 

/* External Module References: */ 

/* (List modules that are called by this module.) */ 

/* 7 

/* Change Activity: */ 

/* date, author: description of changes */ 

/* (Keep a log of the changes made to this module for) */ 

/* (future reference. ) */ 
/••A************************************************************ 

/* NetView High-Level Language include files */ 

%INCLUDE DSIPLI; /* Include the HLL macros */ 

/* Parameter declarations */ 
/********************************************************************^ 

DCL HLBPTR PTR; /* Pointer to the HLB */ 

DCL CMDBUF CHAR(*) VARYING; /* Buffer for the command */ 

DCL 0RI6BLCK CHAR(40); /* Area for the Origin Block */ 
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/* Other declarations */ 

/********************************************************************/ 

DCL ORIGIN PTR; /* Pointer to the Origin Block */ 

DCL ADDR BUILTIN; /* Builtin function */ 

/* Initialization */ 

/*****************************•****************•*********************/ 

ORIGIN=ADDR(ORIGBLCK); /* Address of the Origin Block */ 

/•A******************************************************************/ 

/* Execution */ 

/***************•********************************************** 

HLBRC = CNM_GOOD; /* Successful completion */ 

END PTMPPLT; 
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Data Queue Management 

NetView utilizes several data and message queues to work in conjunction with hll 
service routines. Information retrieved from these queues, by the getdata function, 
can be manipulated to enhance your network manageability. The following five 
queues are defined for data and message management. 



TRAPQ 



OPERQ 



DATAQ 



IDATAQ 



CNMIQ 



Queue 1 This queue enables the user to access mes- 

sages placed on it after being trapped as a 
result of an issuance of the trap command for 
messages. 

Queue 2 This queue enables the user to access oper- 

ator input, entered by the go or queue 
command. 

Queue 3 This queue enables the user to access data 

type messages placed on it by the send 
message hll service routine (cnmsmsg). 

Queue 4 The initial data queue enables the user to 

access the message that invoked the hll 
command processor by the message auto- 
mation table or which drove dsiexo2A. 

Queue 5 This queue enables the user to access cnmi 

solicited data which was solicited by an issu- 
ance of the hll cnmi service routine (cnmcnmi). 
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Sending Information 

The following is an example of sending messages to different destinations. 

/* SEND A MULTILINE MESSAGE TO USER */ 

/***************************************************************** 

CALL CNMSMSG(HLBPTR,'Line 1 of 3 ', 'MSG_C ,'OPER' ,' ') 
CALL CNMSMSG(HLBPTR,'Line 2 of 3 ' ,'MSG D' , 'OPER' , ' ') 
CALL CNMSMSG(HLBPTR,'Line 3 of 3 ' , 'MSgV, 'OPER' ,") 

/••♦A************************************************************** 

/* SEND A MULTILINE MESSAGE TO A TASK */ 

/********************************************************************/ 

CALL CNMSMSG(HLBPTR,'Line 1 of 3 ' , 'MSG_C , 'TASK' , '0PER2') 
CALL CNMSMSG(HLBPTR,'Line 2 of 3 ' , 'MSG_D' , 'TASK' , '0PER2') 
CALL CNMSMSG(HLBPTR,'Line 3 of 3 ' , 'MSG_F' , 'TASK' ,'0PER2') 

/**************•*****************************************************/ 
/* SEND A MESSAGE TO THE CONSOLE (only 1-liners)*/ 

CALL CNMSMSG(HLBPTR, 'Hello Sysop * , 'MSG' , 'SYSOP' ,") ; 

/*******•******************************************************* 

/* SEND A MESSAGE TO THE AUTHORIZED RECEIVER */ 

/******************************************************************* 

CALL CNMSMSG(HLBPTR, 'Hello Authrcvr ' , 'MSG' , 'AUTHRCV, ") ; 

/* SEND A MESSAGE TO THE NETWORK LOG */ 

CALL CNMSMSG(HLBPTR,'This should only be in log' , 'MSG' ,'NETVLOG' , "); 

/* SHOW THAT YOU CAN SEND TO SEQLOG */ 

CALL CNMSMSG(HLBPTR,'test msg' , 'MSG', 'SEQLOG' , 'SQLOGTSK'); 

/* SHOW THAT YOU CAN SEND TO A GROUP */ 

CALL CNMSMSG(HLBPTR, 'hello group 1 , 'MSG' , 'OPCLASS' ,'+GR0UPl'); 
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Parsing Input Strings 

Parsing Input String Similar to NetView Command List Language 

The following is an example of parsing the input string similar to the NetView 
command list language. It will parse the first 10 tokens individually, just as 
NetView command list language would parse them into &1, &2, etc.. It will also set 
an equivalent variable to &parmstr. 



/•••A****************************************************************/ 

/* */ 

/* Other Declarations */ 

/* 7 

/••A*****************************************************************/ 

DCL (CLIST1,CLIST2,CLIST3, 

CLIST4,CLIST5,CLIST6, 

CLIST7,CLIST8,CLIST9, 

CLIST10,PARMSTR) 

CHAR(255) VARYING; 
DCL PARMCNT FIXED BIN(31,0); 



/* Number of tokens parsed 



7 



/A*******************************************************************/ 
/* 7 

/* Execution */ 



******************************************************************** 



r 
i 

CNMSSCAN 

DATA(CMDBUF) 

FORMAT ( '%*S%S%S%S%S%S%S%S%S%S' 

COUNT (PARMCNT) 

Pl(CLISTl) 

P2(CLIST2) 

P3(CLIST3) 

P4(CLIST4) 

P5(CLIST5) 

P6(CLIST6) 

P7(CLIST7) 

P8(CLIST8) 

P9(CLIST9) 

PIO(CLISTIO); 

CNMSSCAN 

DATA(CMDBUF) 
FORMAT ('%*S%H') 

COUNT (PARMCNT) 
Pl(PARMSTR); 



/* Parse like NetView Command 



/* 
sS')/* 

/* 

/*■ 

/* 

/* 

/* 

/* 

/* 

/* 

/* 

/*■ 

/* 

/* 

/* 

/* 
/* 
/* 
/* 
/* 



...List Language parses 


7 


...input is in cmdbuf 


7 


...parse each token by blanks 


7 


...but skip the command 


7 


...number of tokens parsed 


7 


...first token 


V 


...next token 


*/ 


. . .next token 


*/ 


...next token 


V 


...next token 


V 


...next token 


*/ 


...next token 


V 


...next token 


V 


...next token 


*/ 


...last token 


V 


Parse like NetView Command 




...List Language parses 


*/ 


...input is in cmdbuf 


V 


...skip over command, then 


V 


...put all parms in a target 


V 


...number of tokens parsed 


*/ 


...first token 


*/ 
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Parsing Input String Similar to REXX 

The following is an example of parsing input strings. Using the following example, 
pl/i will parse the first 4 tokens individually, and then put the rest of the input into 
the fifth token. The rexx language parses the following statement in this way. 



arg tokenl token2 token3 token4 token5 



/♦••A************************************************ 

/* 7 

/* Other Declarations */ 

/* 7 

/••it***************************************************************** 

DCL (T0KEN1,T0KEN2,T0KEN3, 
T0KEN4,T0KEN5,MSGSTR) 

CHAR(255) VARYING; 
DCL PARMCNT FIXED BIN (31,0); 



/* Number of tokens parsed 



7 



/* 7 

/* Execution */ 

/* 7 

/it************************************************************ 



CNMSSCAN 
DATA(CMDBUF) 
FORMAT ( '%*S%S%S%S%S%H ' ) 



COUNT (PARMCNT) 

Pl(TOKENl) 

P2(T0KEN2) 

P3(T0KEN3) 

P4(T0KEN4) 

P5(T0KEN5); 



CNMSSCAN 
DATA(CMDBUF) 
FORMAT ( , %*S%{-'} , ) 

COUNT (PARMCNT) 
Pl(MSGSTR); 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



/* 
/* 
/* 
/* 
/* 
/* 



Parse like TOKEN parses... 

...input is in cmdbuf 

...parse each token by blanks 

...but skip the command and 

...last token gets rest of 

...the input. 

...number of tokens parsed 

...first token 

...next token 

...next token 

...next token 

...last token gets the rest 

...of the input string 

Parse like ARG parses... 
..input is in cmdbuf 
..skip over command, then 
..put all parms in a target 
..number of tokens parsed 
..first token 



7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 



7 
7 
7 
7 
7 
7 
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Parsing Input String 



The following is another example of parsing. Based upon the c sscanf function, 
cnmscan allows for both parsing and conversion in a single step, and allows delim- 
iting the input on any character desired. 



/* 7 

/* Other Declarations */ 

/* 7 

DCL CNT FIXED BINARY (31, 0) ; /* Number of strings parsed 

DCL INPUTJTR CHAR(256) VARYING; /* Sscan input string 

DCL FORMAT CHAR(256) VARYING; /* Sscan format string 

DCL MSGBUF CHAR (256) VARYING; /* Message buffer 
DCL (CH1,CH2,CH3,CH4,CH5,CH6) 

CHAR(8) VARYING; /* Char vars 
DCL (FX1,FX2,FX3) 

FIXED BINARY (31,0); /* Fixed vars 



7 
7 
7 
*/ 



*/ 

7 



/* 7 

/* Execution */ 

/* 7 

/••••A******************************************************* 



/* Parse out a string */ 



INPUT_STR='parml 
'parm2 
'parm3 
' 10000 
'200 
■FFFFF 
'01XYZ2 1 .. 
' parm4'; 



/* Set input string up 



7 
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FORMAT= 



'%S' 
•%4S' 

•%S' 
'%*S' 

'%D' 
'%2D' 

»%*S' 

'%X' 
'%{ Q10} 



•%{2ZYX}' 



•%{-4}'; 



/* 
/* 
/* 

/* 
/* 

/* 
/* 



/* 

/* 



The format string says to: 

(1) Find a character string 

(2) Find a 4-byte character 

string 

(3) Find a character string 

(4) Skip over a character 

string 

(5) Find a decimal string 

(6) Find a 2-byte decimal 
string 

(7) Skip over a character 
string 

(8) Find a hex string 

(9) Find a string that contains 
one of the bracketed 
characters, stop scanning 
when a non-bracketed 
character is found */ 

(10) Find a string that contains 
one of the bracketed 
characters, stop scanning 
when a a non-bracketed 
character is found */ 

(11) Find a string that 
does NOT contain a 4, stop 
scanning when a 4 is found */ 



V 

7 
7 

*/ 

7 

7 

7 
7 



CALL CNMSCAN(HLBPTR, 




/* 


Scan can the input string. 


..*/ 


INPUT STR, 




/* 


..input is in here 


V 


FORMAT, 




/* 


..format string 


V 


CNT, 




/* 


..number of string parsed 


V 


CHI, 




/* 


..character string 


V 


CH2, 




/* 


..character string 


7 


CH3, 




/* 


..character string 


*/ 


FX1, 




/* 


..decimal string 


V 


FX2, 




/* 


..decimal string 


*/ 


FX3, 




/* 


...hex string 


V 


CH4, 




/* 


..character string 


V 


CH5, 




/* 


..character string 


V 


CH6, 




/* 


..character string 


V 


" ); 




/* 


...not used 


*/ 


/************************************** 


****************************! 


k**f 


/* After executing, the vari 


ables 


haw 


» the following values: 


V 


/* 








V 


/* CHI = "parml" 








V 


/* CH2 = "parm" 








V 


/* CH3 = "2" 








*/ 


/* FX1 - 10000 Decimal, 


2710 


He) 


< 


V 


/* FX2 = 20 Decimal , 


14 


He) 


< 


V 


/* FX3 = 1048575 Decimal, 


FFFFF He) 


< 


V 


/* CH4 = " 01" 








*/ 


/* CH5 = "XYZ2" 








V 


/* CH6 = " parm" 








V 


/* 








V 



/* V 

/♦••Ik****************************************************************/ 
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Synchronous Commands 

The following is an example of an hll command processor invoking another 
command. The command could be another hll command, a vtam command, or a 
NetView command. 

/* V 

/* Execution */ 

/* */ 

/••••••••••••A************************************** 

/* Issue the VTAM command D NET,APPLS */ 

CALL CNMCMD(HLBPTR, /* Invoke the command... */ 

'D NET,APPLS'); /* ...text of the command to run */ 



46 NetView Customization: Using PLI and C 



Sending Commands 

The following is an example of sending a command to execute under another task. 
The command to be run under the other task could be another hll command, a 
vtam command, or a NetView command. 

You can use this process to execute commands under data services tasks (dst), 
other operator station tasks (ost), or the primary poi task (ppt). 

/•A************************************************************ 

/* 7 

/* Execution */ 

/* 7 

/* Issue the LOGOFF command on a task called OPERl */ 

/* Send the command... */ 

(* ...text of the command to run */ 

...this is a command */ 

...run it on a task */ 

...task name is OPERl */ 

SELECT; 

WHEN(HLBRC=CNM GOOD) 

CALL CNMSMSG"(HLBPTR, /* Inform user of success... */ 

'OPERl logoff successfully scheduled 1 , /* ...text of msg*/ 



CNMSMSG(HLBPTR, 


/' 


'LOGOFF', 


/■ 


'COMMAND', 


/' 


'TASK', 


/' 


'OPERl'); 


/' 



'MSG', 


/* ...this is a message 


7 


'OPER', 


/* ...to the operator 


7 


"); 


/* ...not used 


7 


WHEN (HLBRC=CNM_TASK_INACTIVE) 






CALL CNMSMSG(HLBPTR, 


/* Inform user task not active. 


..*/ 


'OPERl not active', 


/* ...text of message 


7 


'MSG', 


/* ...this is a message 


7 


'OPER', 


/* ...to the operator 


7 


"); 


/* ...not used 


7 


OTHERWISE 






CALL CNMSMSG(HLBPTR, 


/* Inform user bad re... 


7 


'Unexpected RC from CNMSMSG', /* ...text of message 


7 


'MSG', 


/* ...this is a message 


7 


'OPER', 


/* ...to the operator 


7 


"); 


/* ...not used 


7 


:ND; 


/* of select 


7 



HLBRC=CNM_G00D; /* Clear RC 
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Waiting and Trapping 

The following is an example of how to issue a command, trap the output of the 
command, and respond depending on the output that is encountered. It will acti- 
vate the given lu and issue an appropriate message. 

The syntax that it checks for is: 

PACTLU luname 

Where luname is the name of the lu to be activated 



***************************************************************** 



/ 

/* 

/* Other Declarations 

/* V 

/********************************************************************/ 



/ 

V 
V 



DCL GETBLOCK CHAR (40); 
DCL GETPTR PTR; 
DCL INBUF CHAR(256) VAR; 
DCL NODENAME CHAR (8) VAR; 
DCL STATUS CHAR(8) VAR; 
DCL CNT FIXED BIN(31,0); 



/* Area for the Orig Block 
/* Pointer to the Orig Block 
/* Buffer area for messages 
/* Nodename to be activated 
/* Status of the resource 
/* Number of elements parsed 



*/ 
*/ 
*/ 
*/ 
*/ 
*/ 



/••••♦♦•A************************************************************/ 
/* */ 

/* Execution */ 

/* */ 

/A*******************************************************************/ 



GETPTR=ADDR(GETBLOCK) ; 
/ 



/* Address the Orig Block 



******************************************************************** 



Scan the input for the lu name to activate 



/********************************************************************, 



CALL CNMSCAN(HLBPTR, 


/* Parse the input ... */ 


CMDBUF, 


/* ...command line is the input */ 


'%*S%8S', 


/* ...skip over command name */ 


CNT, 


/* ...returned */ 


NODENAME) ; 


/* ...nodename */ 
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IF CNT=1 THEN 
DO; 
CALL CNMCMD(HLBPTR, 
1 TRAP AND 
CALL CNMCMD(HLBPTR, 
CALL CNMCMD(HLBPTR, 
CALL CNMGETD(HLBPTR 
'GETMSG', 
INBUF, 
256, 

GETBLOCK, 
TRAPQ, 

l); 



/* Nodename specified? */ 

/* Yes... */ 

/* Trap the following VTAM msgs */ 

SUPPRESS ONLY MESSAGES 1ST*'); 

1 V NET,ACT,ID='||NODENAME); /* Activate node*/ 

' WAIT 10 SECONDS FOR MESSAGES'); /* Wait... */ 

/* Get the first trapped msg... */ 

/* ...function is get a msg */ 

/* ...result goes here */ 

/* ...max input length */ 

/* ...must provide a work area */ 

/* ...message is trapped */ 

/* ...get the first one */ 



J**************************************************************** / 

/* Loop through messages until IST093I is found or no more */ 
/* ...messages are left */ 

DO WHILE(GETPTR->0RIG_BL0CK.0RIG_PR0CESS-='IST093r & 
HLBRC=CNM_G00D) ; 
CALL CNMCMD(HLBPTR,' WAIT CONTINUE'); /* Wait for next msg... 



CALL CNMGETD(HLBPTR, 
'GETMSG', 
INBUF, 
255, 

GETBLOCK, 
TRAPQ, 

i); 

END; 

IF (HLBRC=CNM_G00D 



/* Get the next trapped msg... 



/* 
/* 
/* 
/* 
/* 
/* 



..function is get a msg 
..result goes here 
..max input length 
..must provide a work area 
..message is trapped 
..get the top one on queue 



/* Did we find IST093I? 



GETPTR->0RIG_BL0CK.0RIG_PR0CESS=' IST093I ' ) THEN 



CALL CNMSMSG(HLBPTR, 

'RESOURCE ■ | | NODENAME | 

'MSG', 
'OPER', 



ELSE 



/* Inform user activation worked 

' NOW ACTIVE', 

/* ...text of message 

...single line message 

...to the operator 

...not needed 

IST093I not found, must be 

...an error 

Inform user activation failed 



/* 
/* 
/* 
/* 



/ 



CALL CNMSMSG(HLBPTR, 

'ERROR - ACTIVATION UNSUCCESSFUL', 

/* ...text of message 
'MSG', /* 

'OPER', /* 

"); /* 

END; 
ELSE /* 

CALL CNMSMSG(HLBPTR, /* 

•ERROR - NODENAME NOT SPECIFIED', 

/* ...text of message 
'MSG', /* ...single line message 

'OPER', /* ...to the operator 

"); /* ...not needed 



...single line message 
.. .to the operator 
. . . not needed 

Nodename not specified 
Inform user need more args 



V 

V 
V 
V 
V 
V 
7 
V 

*/ 

*/ 

V 
V 

V 

*/ 

V 
V 

V 
V 
V 
V 

V 

7 

V 
V 
V 

*/ 
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Retrieving Information 

The following gives an example of how an hll command processor or user exit 
routine can retrieve information from NetView. Assembler language command 
processors and user exit routines need DSECTs to access information about 
NetView. hll command processors and user exit routines can access some of this 
information as shown below. Many variables are available. Please refer to the 
command and service routine reference "CNMINFC (CNMINFOC) - Query NetView 
Character Information" on page 209 and "CNMINFI (CNMINFOI) - Query NetView 
Integer Information" on page 211 for an exhaustive list of the values supported. 

/••A****************************************************** 

/* */ 

/* Other Declarations */ 

/* 7 

DCL CDATA CHAR(18) VAR; /* Character information holder */ 
DCL IDATA FIXED BIN(31,0); /* Integer information holder */ 



/* 7 

/* Execution */ 

/* 7 

/••♦♦A*************************************************************** 



CALL CNMINFC (HLBPTR, 


/* 


'DATETIME', 


/* 


CDATA, 


/* 


18); 


/* 


CALL CNMINFI (HLBPTR, 


/* 




/* 


'COLORS', 


/* 


IDATA) ; 


/* 



Retrieve the date & time... 
...specify the variable 
...result goes here 
...at most 18 bytes 
Retrieve the number of colors 
...that the terminal supports 
...specify the variable 
...result goes here 



7 

7 
7 
7 
7 
7 
7 
7 
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Command List Variable Access 

The following example illustrates the capability of updating common global vari- 
ables. This example simply increments a global variable named "gvariable" by 1. 

Task globals are updated and read the same way. The only difference is the pool 
name that is specified. 



/•A******************************************************************/ 

/* */ 

/* Other Declarations */ 

/* */ 

/********************************************************************/ 

DCL DATA IN CHAR(24) VAR; /* Holds the input data */ 

DCL DATA_IN_LEN FIXED BIN(31,G) INIT(24); /* Max length of input*/ 

/********************************************************************/ 

/* 7 

/* Execution */ 

/* V 

/********************************************************************/ 



/ 



******************************************************************** 



Find the value of the variable 



/ 



/******************************************************************** , 



CALL CNMVARS(HLBPTR, 


/* R 


'GET', 


/* • 


DATAJN, 


/* • 


DATA IN LEN, 


/* • 


'GVARIABLE', 


/* • 


'CGLOBAL'); 


/* • 



Read the global variable... 
...function is read 
...result goes here 
...truncate after 24-bytes 
...variable name is GVARIABLE 
...variable pool is CGLOBAL 



V 
V 
V 
V 
V 
V 



DATA_IN=DATA_IN+1; 



/* Increment Variable 



/ 



******************************************************************** 



/ 



/* Set the global variable */ 

/********************************************************************/ 

CALL CNMVARS(HLBPTR, /* Update the global variable... */ 

..function is write */ 
..data is here */ 

..not used */ 

..variable name is GVARIABLE */ 
..variable pool is CGLOBAL */ 



'PUT', 


/* • 


DATAJN, 


/* • 


» 


/* • 


'GVARIABLE', 


/* • 


'CGLOBAL'); 


/* • 
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Using Locks 



The previous example illustrated the capability of updating common global vari- 
ables, but it did not protect the updating of the variable named "gvariable" by using 
a lock. The need for protecting the updating needs to be assessed on a case-by- 
case basis. This example has been modified to obtain a lock before attempting the 
update. 

The lock name can be the same as the global variable, or it can be different. 

If you decide that it is important to synchronize the updating of a variable, you can 
use the lock method shown below or you may wish to run all the updates on a 
given task. Since only one process can occur on a task at a time, the updates will 
be serialized. Note that this could be any task, including the ppt. 

DCL DATA-IN CHAR(24) VAR; /* Holds the input data */ 

DCL DATAJNJ-EN FIXED BIN (31, G) INIT(24); /* Max length of input */ 

/* Obtain the lock to secure the accuracy of the update */ 

CALL CNMLK(HLBPTR, /* Obtain the Lock ... */ 

'LOCK', /* ...function is obtain lock */ 

'GVARIABLE', /* ...name of the lock */ 

", /* ...not used */ 

'WAIT'); /* ...wait if not available */ 

/•••••♦••••a******************************************* 

/* Find out the value of the variable */ 

CALL CNMVARS(HLBPTR, /* Read the global variable... */ 

'GET', /* ...function is read */ 

DATA__IN, /* ...result goes here */ 

DATAJN_LEN, /* ...truncate after 24-bytes */ 

'GVARIABLE', /* ...variable name is GVARIABLE */ 

'CGLOBAL'); /* ...variable pool is CGLOBAL */ 

DATA_IN=DATA_IN+1; /* Increment Variable */ 

/* Set the global variable */ 

CALL CNMVARS(HLBPTR, /* Update the global variable... */ 

'PUT', /* ...function is write */ 

DATAJN, /* ...data is here */ 

/* ...not used */ 

'GVARIABLE', /* ...variable name is GVARIABLE */ 

'CGLOBAL'); /* ...variable pool is CGLOBAL */ 

/* Release the lock to let other tasks update GVARIABLE */ 

CALL CNMLK(HLBPTR, /* 

'UNLOCK', /* 

'GVARIABLE', /* 

/* 
"); /* 



Free the Lock ... 


V 


...function is free lock 


7 


...name of the lock 


V 


...not used 


V 


...not used 


*/ 
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Operator Input 



The following is an example of how to code an HLL command processor to accept 
operator input in single-line mode. The interface is similar to the apause function 
of the NetView command list language. Input is requested by the application using 
the wait for opinput command, input is retrieved by the application using the 
cnmgetd service routine and the operator can respond by using the go command. 

/•••••••A*********************************************************** 
/* V 

/* Other Declarations */ 

/* V 

/•A******************************************************************/ 

DCL GETBLOCK CHAR(40); /* Area for the Orig Block */ 

DCL GETPTR PTR; /* Pointer to the Orig Block */ 

DCL DATA_INCHAR(256) VAR; /* Buffer area for messages */ 

/♦•••it***************************************************************/ 

/* V 

/* Execution */ 

/* */ 

GETPTR=ADDR (GETBLOCK); /* Address the Orig Block */ 

CALL CNMSMSG(HLBPTR, /* Send a message... */ 

'ENTER OPERATOR INPUT DATA', /* ...text of message */ 

'MSG', /* ...single line message */ 

'OPER', /* ...to the invoking operator */ 

"); /* ...not used '*/ 

CALL CNMCMD(HLBPTR,' WAIT 10 SECONDS FOR OPINPUT'); /* Wait... */ 

IF HLBRC=CNM_OPINPUT_ON_WAIT THEN 
DO; /* Operator input supplied... */ 



CALL CNMGETD(HLBPTR, /* Get the first trapped msg... */ 

'GETMSG', /* ...function is get a msg */ 

DATAJN, /* 

256, /* 

GETBLOCK, /* 

OPERQ, /* 

1); /* 



..result goes here */ 
..max input length */ 
..must provide a work area */ 
..message is on OPINPUT QUEUE*/ 
..get the first one */ 



CALL CNMSMSG(HLBPTR, /* Send a message... */ 

'OPERATOR INPUT IS: | (DATAJN, /* ...text of message */ 

'MSG', /* ...single line message */ 

'OPER', /* ...to the invoking operator */ 

"); /* ...not used */ 
END; 

ELSE /* No operator input supplied */ 

CALL CNMSMSG(HLBPTR, /* Send a message... */ 

'NO OPERATOR INPUT SUPPLIED', /* ...text of message */ 

'MSG', /* ...single line message */ 

'OPER', /* ...to the invoking operator */ 

"); /* ...not used */ 
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VIEW Command Processor 

The following is an example of using the full-screen view command processor. 
First it creates the local variable called parmi, and the variable is initialized. The 
view command processor is invoked, displaying a full-screen panel. The following 
panel is used as input by the view command. For more information on view see the 
NetView Customization Guide. 

The panel that is invoked by the following example appears below: 

+TESTHLL %TEST THE. VIEW COMMAND WITH HLL 1 

${ Example of using the VIEW command with HLL: f } 

$| Notes: The field below, PARMI, is defined as a variable I \ 

$ } by preceding the string PARMI with an ampersand (&). j < 



$ f INPUT===«=> SPARM1 \ 

%Acti on=*= s >" 
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/* V 

/* Other Declarations */ 

/* V 

DCL DATA_INCHAR(48) VAR; /* Input buffer for results */ 

/* V 

/* Execution */ 

/* V 

CNMVARPOOL FUNC('DCL') /* Declare to local pool... */ 

/* ...prior to invoking VIEW */ 

NAME('PARMl') /* ...name is Parml */ 

POOL ('LOCAL'); /* ...the pool is local */ 

CNMVARPOOL FUNC('PUT') /* Initialize PARM1... */ 

DATA('the contents of parml go here') /* ...data */ 

NAME('PARMl') /* ...name of local variable */ 

POOL ('LOCAL'); /* ...the pool is local */ 

/* Invoke the VIEW command. Give the task name as a unique */ 

/* name to go on the View Stack. */ 

CNMCOMMAND DATA('VIEW '|| ORIGIN->ORIG_TASK| |' TESTHLL NOMSG NOINPUT'); 
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Message Processing 



The following example lists the message attributes of a message. The invocation 
must be as a result of an entry in the message automation table, which is docu- 
mented in the NetView Administration Reference. This example will function cor- 
rectly for both single line messages and multiple line messages. 



DCL GETBLOCK CHAR (40); 
DCL 6ETPTR PTR; 
DCL INBUF CHAR(256) VAR; 
DCL DATAJN CHAR(12) VAR; 
DCL ATTRTl2) CHAR(8) INIT( 



/* Area for the Orig Block 
/* Pointer to the Orig Block 
/* Buffer area for messages 
/* Attribute result 
/* 12 message attributes: 



*/ 
*/ 

V 
V 
V 



'AREAID' ,'DESC , 'JOBNAME' , 'JOBNUM' , 'MCSFLAG' ,'MSGTYP', 
'REPLYID' , 'ROUTCDE' , 'SESSID' , ' SMSGID' , ' SYSCONID' , ' SYSID' ) ; 

/* V 

/* Execution */ 

/* */ 



GETPTR=ADDR(GETBLOCK) ; 
CALL CNMGETD(HLBPTR, 
'GETMSG', 

INBUF, 

256, 

GETBLOCK, 

IDATAQ, 

l); 

DO WHILE(HLBRC=CNM GOOD 

HLBRC=CNM~DATA_TRUNC) ; 
DO 1=1 TO 12; 
CALL CNMGETA(HLBPTR, 
ATTR(I), 
DATAJN, 
12, 

IDATAQ); 
CALL CNMSMSG(HLBPTR,ATTR(I) | | ' 
END; 
CALL CNMSMSG(HLBPTR,'LINETYPE = 

'MSGVOPER','') 
CALL CNMSMSG(HLBPTR,'HDRMTYPE 

'MSGVOPER',") 
CALL CNMSMSG(HLBPTR,'MSGID 

'MSGVOPER',") 
CALL CNMSMSG(HLBPTR,'MSGSTR 

'MSGVOPER',' ') 
CALL CNMGETD(HLBPTR, 
'GETLINE', 
INBUF, 
255, 

GETBLOCK, 
IDATAQ, 

1); 
END; 
HLBRC=CNM_G00D; 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 

/* 
/* 
/* 
/* 
/* 
/* 



Address the Orig Block 

Get the first line of the msg 
..function is get a msg 
..result goes here 
..max input length 
..must provide a work area 
..message from automation 
..get the first line of msg 

Loop through the messages... 

/* ...ignoring truncation 

For 12 possible attributes... 

Get the Ith attribute... 

...Ith member of array 

...result goes here 

...at most 12 bytes 

...on the initial data queue 

| |DATA_IN, 'MSGVOPER 1 ,"); 



*/ 
*/ 
*/ 

V 

*/ 

*/ 
V 

*/ 
*/ 

V 

*/ 

V 

*/ 
*/ 
*/ 

V 



|GETPTR->ORIG_BL0CK.0RIG_LINE_TYPE, 
|GETPTR->ORIG_BLOCK.ORIG_MSG_TYPE, 
|GETPTR->ORIG_BLOCK.ORIG_PROCESS, 
I INBUF, 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



Get next line of message... 

..function is get next line 

..result goes here 

..max input length 

..must provide a work area 

..message is from automation 

..get the next line 
Of DO WHILE 
Clear RC 



7 
V 
*/ 

V 
V 

*/ 

V 
V 

* / 
/ 
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Scope Checking 



The following is an example of the scope checking capabilities provided by 
NetView. In this example, the user is required to set up the following elements for 
the command (shown below): 

1. operator id 

2. operator classes that can access the command 

3. operator profile 

The command gives the return code that the scope check service routine returned 
to the operator. 

The syntax that this command checks for is: 
PSPCCKO PARMx(VALx) 

The following is the setup for the scope check example. 

In DSIPARM(DSICMD): 

• Define the operator classes that can access the command, its keywords, and 
its keyword values. 



• 



The example below says that the command PSPCCKO can be executed by 
operators in scope class 1 and 2. Scope class 1 can issue any keyword or 
keyword value, but scope class 2 cannot use the value of VAL1 with keyword 
PARM2, and scope class 2 cannot issue PARM3 at all. 



PSPCCKO 


CMDMDL 


MOD=PSPCCKO,RES=N,TYPE=RD 




CMDCLASS 


1,2 


PARM2 


KEYCLASS 


1,2 


VAL1 


VALCLASS 


1 


PARM3 


KEYCLASS 


1 


VAL1 


VALCLASS 


1 



In DSIPARM(DSIOPF): 

• Define the operator ids and the profiles that the operator ids can use. 

JOE OPERATOR PASSWORD=USER 
PROFILEN DSIPR0F3 

In DSIPRF(profilename): 

• Define the operator class value that will correspond to the profile that the oper- 
ator logs on with. 

DSIPR0F3 PROFILE 
OPCLASS 3 
END 
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A********************************************************************/ 

/* V 

/* Other Declarations */ 

/* V 

A********************************************************************/ 

V 
V 
*/ 
*/ 
V 
V 
V 
V 



DCL INBUF CHAR(8G) VAR; 


/* 


DCL CMDNAMEV CHAR (8) VAR; 


/* 


DCL KEYWORDV CHAR (8) VAR; 


/* 


DCL KEYVALUEV CHAR (8) VAR; 


/* 


DCL CMDNAME CHAR (8); 


/* 


DCL KEYWORD CHAR(8); 


/* 


DCL KEYVALUE CHAR(8); 


/* 


DCL CNT FIXED BIN(31,0); 


/* 



Buffer area for messages 
Command that invoked us 
Keyword of invocation 
KeyValue of invocation 
Command that invoked us 
Keyword of invocation 
KeyValue of invocation 
Number of elements parsed 



/********************************************************************/ 

/* 7 

/* Execution */ 

/* V 

/********************************************************************/ 

/********************************************************************/ 
/* Scan the keyword and the value */ 



/ 



******************************************************************** 



/ 



CALL CNMSCAN(HLBPTR, 


/* f 


>arse the input ... 


V 


CMDBUF, 


/* • 


..command line is the input 


V 






/* SYNTAX OF COMMAND IS: 


V 




/* 


CMDNAME KEYWORD (KEYVALUE) 


*/ 




/* 




*/ 




/* Scan for the: 


7 


'W'll 


/* 


..command name 


V 


'%*{ I'll 


/* 


..skip over leading blanks 


V 


'%H}'II 


/* 


..keyword up to "(" 


V 


'WW 


/* 


..skip over "(" 


V 


'%{-)}•, 


/* 


..keyvalue up to ")" 


V 


CNT, 


/* 


..number strings parsed 


V 


CMDNAMEV, 


/* 


. . command goes here 


V 


KEYWORDV, 


/* 


..keyword goes here 


V 


KEYVALUEV) ; 


/* 


..keyvalue goes in here 


V 


CMDNAME=CMDNAMEV; 


/* < 


■let fixed length value 


*/ 


KEYWORD=KEYWORDV; 


/*( 


let fixed length value 


V 


KEYVALUE=KEYVALUEV; 


/*< 


■let fixed length value 


*/ 


IF CNT=3 THEN 


/M 


inough parms specified? 


V 


CALL CNMSCOP(HLBPTR, 


/*! 


>cope check the input... 


*/ 


CMDNAME, 


/* 


...the command 


V 


KEYWORD, 


/* 


..the keyword 


V 


KEYVALUE) ; 


/* 


...the value 


V 


ELSE 


/*! 


lot enough parms specified 


V 


HLBRC=CNMJADJNVOCATION; 


/*! 


Set re 


V 
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/••••A************************************************ 

/* Inform user of the return code results... */ 

/**********************************************************•** 



SELECT; 






WHEN(HLBRC=CNM GOOD) 






DO; 


/* Operator 


V 




/* has 


7 




/* passed 


V 


END; 


/* scope checking 


V 



WHEN(HLBRC=CNM_KEYWORD NA) 
CALL CNMSMSG(HLBPTR,» Not authorized to use KEYWORD '| (KEYWORD, 

'MSGVOPERV); 
WHEN(HLBRC=CNM VALUE NA) 
CALL CNMSMSGTHLBPTR, ' Not authorized to use VALUE « ||KEYVALUE, 

'MSGVOPERV'); 
WHEN (HLBRC=CNM_BAD_INVOCATION) 
CALL CNMSMSGTHLBPTR, ' Not enough partus specified', 
•MSGVOPERV); 
OTHERWISE 
CALL CNMSMSG(HLBPTR,' RC not recognized... ' | |HLBRC, 

'MSGVOPERV'); 
END; 
HLBRC=CNM_GOOD; /* Clear RC */ 
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Altering Data 



This DSIEX02A exit routine changes the echoed command message (msgtype= # ) to 
be more informative by giving the time as well as the fact that the command was 
entered. 

Example output with input of WHO: 

Without exit: 
WHO 

With exit: 
Command entered was: "WHO" at 12:00:00 

DSIEX2A: PROC(HLBPTR,CMDBUF,ORIGBLCK) OPTIONS (MAIN, REENTRANT); 

/•A******************************************************* 

/* */ 



/* Change Activity: */ 

/* date, author: description of changes */ 

/•••••A*********************************************** 

/* */ 

/* Parameter Declarations */ 

/* V 

/••A******************************************* 

DCL HLBPTR PTR; /* Pointer to the HLB */ 

%INCLUDE DSIPLI; /* Include the HLL macros */ 

DCL CMDBUF CHAR(*) VARYING; /* Buffer for the command */ 

DCL ORIGBLCK CHAR(40); /* Area for the Orig Block */ 

DCL ORIGIN PTR; /* Pointer to the Orig Block */ 

DCL ADDR BUILTIN; /* Bui 1 tin function */ 

ORIGIN=ADDR(ORIGBLCK) ; /* Address the Orig Block */ 

/* */ 

/* Other Declarations */ 

/* */ 

/♦•••♦•A********************************** ***************************/ 

DCL GETBLOCK CHAR(40); /* Area for the Orig Block */ 

DCL DATAIN CHAR(255) VAR; /* Old command text */ 

DCL TIME CHAR(256) VAR; /* Area for time */ 
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/* V 

/* Execution */ 

/* V 



GETPTR=ADDR (GETBLOCK); 


/* 


Address the Orig block 


V 


CNMINFOC 


/* 


Retrieve the time... 


V 


ITEM('TIME') 


/* 


...variable is time of day 


V 


DATA(TIME) 


/* 


...the result goes here 


V 


LENG(256); 


/* 


...max length of 256 


V 


CNMGETDATA 


/* 


Peek the msg before altering 


V 


FUNC('PEEKLINE') 


/* 


...subf unction is PEEK 


*/ 


QUEUE(IDATAQ) 


/* 


...initial data queue 


V 


DATA(DATAIN) 


/* 


...result goes here 


V 


LENG(256) 


/* 


...max length is 256 


V 


ORIGIN (GETBLOCK) 


/* 


...use new Orig block 


*/ 


LINE(l); 


/* 


...check the first line 


V 


IF GETPTR->ORIG MSG TYPE ='*' THEN 


/* Echo'ed message? 


V 


CNMALTDATA 


/* 


Replace the text ... 


V 


FUNC('REPLINE') 


/* 


...function is replace 


*/ 


QUEUE (IDATAQ) 


/* 


...initial data queue 


V 


DATA ('Command entered was 


: "'IIDATAINM'" at ' I |TIME) 






/* 


...text of new message 


V 


ORIGIN (GETBLOCK) 


/* 


...use Peeked Orig block 


V 


LINE(l); 


/* 


...replace the first line 


V 


HLBRC=CNM GOOD; 


/* 


Clear RC 


V 


END DSIEX2A; 
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Storage Access 



The following example illustrates how to display the character representation of 
the contents of the storage that NetView can access. For example, after locating 
the address of the main vector table using dispmod osimntex, you can display the 
first 4 bytes of the dsimvt control block. For NetView R3 this will contain the char- 
acter string NV13. 



DCL NUM PARMS FIXED BIN(31) 
DCL XADDR FIXED BIN (31) 

DCL NUM_BYTES FIXED BIN (31) 
DCL INPUTJFR CHAR(4096); 
DCL SOURCE_PTR PTR; 
DCL I FIXED BIN(31); 



/* 
/* 
/* 
/* 
/* 
/* 



Number of parms passed 
Hex value of source_ptr 
Number of bytes to display 
Buffer where data is copied 
Address to copy from 
Work counter 



V 

*/ 

V 

*/ 
*/ 

V 



/* V 

/* Execution */ 

/* */ 

/••••A*********************************************** 



CNMSSCAN DATA(CMDBUF) 


/* Scan the command for: 


7 


FORMAT ('%*S' || 


/* ...skip the command 


*/ 


'%X'|| 


/* ...save the source address 


7 


'%X') 


/* ...save the length 


7 


COUNT (NUM_PARMS) 


/* ...number of parms scanned 


7 


PI (XADDR) 


/* ...the address to display 


7 


P2(NUM BYTES); 


/* ...for this number of bytes 


7 


SELECT; 






WHEN(NUM_PARMS-=2) 


/* Did they give an address and 






... a length? 


7 


CNMSENDMSG 


/* No, give error message... 


7 


DATA(' INVALID NUMBER OF PARAMETERS') /* ...text 


7 


MSGTYPE('MSG') 


/* . . . message 


*/ 


DESTTYPE COPER'); 


/* ... to the operator 


*/ 



WHEN(NUM_BYTES<=0) /* Did they give a valid length ?*/ 

CNMSENDMSG /* No, give error message... */ 

DATA(' INVALID LENGTH GIVEN') /* ...text */ 

MSGTYPE('MSG') /* ... message */ 

DESTTYPE('OPER'); /* ... to the operator */ 

WHEN(NUM_BYTES>=4096) /* Did they give a valid length ?*/ 

CNMSENDMSG /* No, give error message... */ 

DATA(' INVALID LENGTH GIVEN, MUST BE LESS THAN '|| 

'OR EQUAL TO FFF') /* ...text of message */ 

MSGTYPE('MSG') /* ... message */ 

DESTTYPE('OPER'); /* ... to the operator */ 
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OTHERWISE 

DO; 

UNSPEC(SOURCE_PTR) = UNSPEC(XADDR); /* assign value into a ptr */ 

CNMCOPYSTR /* Copy storage */ 

FR0M(S0URCE_PTR) /* ...from the address given*/ 

TO (ADDR( INPUT BFR)) /* ...to the internal buffer*/ 

LENG(NUM_BYTES) /* ...for up to FFF bytes */ 

COPYTYPE('FIXTOFIX'); /* ...data is fixed Ten vars*/ 

IF HLBRC = CNM_G00D THEN /* Good RC ? */ 

DO 1=1 TO NUM_BYTES BY 64; /* Display storage */ 

CNMSENDMSG DATA(SUBSTR(INPUT_BFR,I,64)) /* ...64-byte */ 

MSGTYPE('MSG') /* ...in a message */ 

DESTTYPE COPER'); /* ...to the operator */ 

END; 

ELSE /* Bad RC ~ */ 

CNMSENDMSG /* Send message ... */ 

DATA(' INVALID OR PROTECTED ADDRESS') /*...text */ 

MSGTYPE('MSG') /* ...in a message */ 

DESTTYPE('OPER'); /* ...to the operator */ 

END; /* of otherwise */ 

END; /* of select */ 
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Data Set Access 



The following is an example of opening (using cnmmemo), reading (using cnmmemr) 
and closing (using cnmmemc) NetView partitioned data sets. This example reads a 
member of dsiparm called dsidmn, and displays it to the operator. 

DCL MEMBER CHAR(8); /* Member name to read */ 

DCL DDNAME CHAR (8) ; /* DDNAME to read */ 
DCL TOKEN FIXED BIN(31,0); /* Token used to match open to 

...read and close */ 

DCL MRDATA CHAR(8G) VAR; /* Line that is read */ 

/********************************************************************/ 

/* */ 

/* Execution */ 

/* */ 

/•a****************************************** 

DDNAME='DSIPARM'; 

MEMBERS DSIDMN'; 

/♦A******************************************************** 

/* OPEN THE MEMBER */ 

/•••••♦A**************************************************** 

CALL CNMMEMO(HLBPTR, /* Open the data set member ... */ 

TOKEN, /* ... token returned by HLL */ 

DDNAME, /* ... ddname of PDS */ 

MEMBER); /* ... member name of PDS */ 
IF HLBRC-=CNM_G00D THEN 

CALL CNMSMSG(HLBPTR, /* OPEN failed... */ 
'OPEN FOR DATA SET FAILED RC=' | ICHAR(HLBRC), 

'MSG', /* ...single line message */ 

■OPER', /* ...to the operator */ 

''); /* ...taskname ignored */ 
ELSE 

DO; /* Open was successful... */ 

/•••A********************************************************* 

/* READ THE MEMBER */ 

/******************************************************•*** 

CALL CNMMEMR(HLBPTR, /* Read the first record... */ 

TOKEN, /* ... provide token from OPEN */ 

MRDATA, /* ... result goes here */ 

80); /* ... read 80 bytes */ 

DO WHILE (HLBRC=CNM_G00D); /* Read til EOF */ 

CALL CNMSMSG(HLBPTR, /* Write out last record read... */ 

SUBSTR(MRDATA,1,72),/* ...write first 72 bytes */ 

'MSG', /* ...single line message */ 

'OPER', /* ...to the operator */ 

"); /* ...taskname ignored */ 

CALL CNMMEMR(HLBPTR, /* Read the next record... */ 

TOKEN, /* ... provide token from OPEN */ 

MRDATA, /* ... result goes here */ 

80); /* ... read 80 bytes */ 

END; 

/* CLOSE THE MEMBER */ 

/••♦•••••••••a******************************** 

CALL CNMMEMC(HLBPTR, /* Close the PDS member... */ 

TOKEN); /* ... using the token from OPEN */ 

END; /* End of Open was successful... */ 
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CNMI 

NetView provides the cnmcnmi service routine for use in communicating with 
devices in the network via the Communications Network Management Interface 
(cnmi). Any data that is returned may be accessed using the cnmgetd service 
routine to retrieve records from the cnmi solicited data queue (cnmiq). 

The following example uses the cnmcnmi service routine to send a request product 
set id data request to a specified PU. Any data returned is sent as a message to 
the operator. 



The syntax of the command is: 

PNMVTPU puname <OWN|ALL> 

where: 

puname is the name of the PU to be retrieved (required) 

OWN implies that vital product data is to be 
retrieved for the PU only (default) 

ALL implies that vital product data is to be 
retrieved for the PU and its attached ports 
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/•••••♦••••A*********************************************************/ 

/* */ 

/* Other Declarations */ 

/* */ 

/••••A***************************************************************/ 



DCL RCODE 


FIXED 


BIN (31,0); /* Return code 


7 


DCL COUNT 


FIXED 


BIN(31,0); /* Count of Scanned args 


7 


DCL 


PUNAMEV 


CHAR(8) VAR; /* PUNAME varying length 


7 


DCL 


PUNAME 


CHAR (8); /* PUNAME fixed length 


7 


DCL GETBLOCK CHAR(40); /* Area for the work orig block 


7 


DCL GETPTR 


PTR; 


/* Pointer to the work Orig Block*/ 


DCL DATAIN 


CHAR (1024) VAR; /* Buffer for the RU 


7 


DCL OWNORALL CHAR(8) VAR; /* Own or all placeholder 


*/ 


/••••••A*************************************************************/ 


/* 








7 


/* 
/* 
/* 


Vital Product Data RU definitions 


7 

7 

■ */ 


From the VTAM Programming Manual, a forward RU is defined below 


/* 








7 


/* 


Byte 


Value 


Description 


7 


/* 





81 


Network services, logical services 


7 


/* 


1 


08 


Management services 


7 


/* 


2 


10 


Request code 


*/ 


/* 


3 


00 


Format 


*/ 


/* 


4 


00 


Ignore target names, 


*/ 


/* 






Solicit a reply, and 


*/ 


/* 






No CNM header contained 


7 


/* 


5 


00 


Reserved 


7 


/* 


6-7 


OOOE 


Length of NS RU 


*/ 


/* 


8-15 




NS RU — NMVT ~ documented in SNA Ref Sum 


7 


/* 


8-A 


41038D 


NS Header for NMVT 


*/ 


/* 


B-C 


0000 


Retired 


7 


/* 


D-E 


0111 


PRID 


*/ 


/* 


F 


00 


unsolicited NMVT, 


7 


/* 






only NMVT for this PRID 


7 


/* 


10-16 




One MS major vector 


*/ 


/* 


10-11 


0006 


Length field of PSID (Product Set ID) vector 


7 


/* 


12-13 


8090 


Code point for PSID 


7 


/* 


14-15 




Length of subvector 


V 


/* 


14 


02 


Length of subvector 


7 


/* 


15 


81 


Request information on control unit only 


7 


/* 


15 


83 


Request information on control unit and its 


7 


/* 






attached devices 


7 


/* 


16 


Fl 


From VTAM programming, PU 


7 


/* 


17 


08 


Length of PU name 


7 


/* 


18 


PUNAME 


Eight byte PUNAME, left justified 


7 



20 00 



End of RU 



/ 



**************************************************************** 



DCL FORWARD_RU CHAR(IOO) VAR INIT( 

' 81O81O0OOOOOOOOE41O38D0OOO01 1 1000006809002 ' X) ; 
DCL OWN CHAR(l) VAR INIT('81'X); 
DCL ALL CHAR(l) VAR INIT('83'X); 
DCL PUNAME_HDR CHAR(2) VAR INIT('F108'X); 
DCL ENDOFRU CHAR(l) VAR INIT('O0'X); 
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/* V 

/* Execution */ 

/* V 
/•A*************************************************************** 



RCODE=0; 
GETPTR=ADDR(GETBLOCK) ; 



CALL CNMSCAN(HLBPTR, 


/* S 


CMDBUF, 


/* • 


'%*S%S%S', 


/* • 


COUNT, 


/* • 


PUNAMEV, 


/* • 


OWNORALL) ; 


/* • 


PUNAME=PUNAMEV; 


/* G 



/* Initialize return code 

/* Address the work Orig Block 



Scan the command line... 
..input in in command line 
..skip over the command 
..number of args parsed 
..puname 
..own or all specified 



/* Get fixed length PU name 



V 
V 

*/ 
V 
*/ 

V 
V 
V 



SELECT; 
WHEN(C0UNT=1) 

FORWARD RU=FORWARD RU||0WN 



/* Own or All not specified 
PUNAME HDRj | PUNAME 1 |END0FRU; 

/* Default is OWN 
/* Own or All not specified 
| OWN 1 1 PUNAMEJDR 1 1 PUNAME 1 1 ENDOFRU; 
/* Process OWN 
/* Own or All not specified 
FORWARD_RU=FORWARD_RU| |ALL| |PUNAME_HDR| | PUNAME | | ENDOFRU; 
OTHERWISE" " /* Invalid parm... tell user 
DO; 
CALL CNMSMSG(HLBPTR, ' INVALID COMMAND SYNTAX', /* wrong... 

'MSGVTASK' .ORIGIN ->0RIG_TASK) ; /* ...syntax 
Bad syntax 



WHEN (0WN0RALL=* OWN') 
FORWARD_RU=FORWARD_RU 

WHEN (0WN0RALL=' ALL*) 



RC0DE=8; 
END; 
END; 

IF RCODE = THEN 
DO; 
CALL CNMCNMI(HLBPTR, 

•SENDRPLY', 
FORWARD_RU, 
PUNAME," 
180); 
IF HLBRC=CNM GOOD THEN 
DO; 
CALL CNMGETD(HLBPTR, 
'GETLINE', 
DATAIN, 
1024, 
GETBLOCK, 
CNMIQ, 

l); 



/* Of Select 
/* Good so far? 
/* Yes, continue 

Send RU over the CNMI... 

...expect a reply 

...RU built above 

...to the PUNAME specified 

...timeout after 3 minutes 

Everything OK? 

Yes, continue 

Read in the first RU returned 

...a single RU 

...into here 

...truncate after 1024-bytes 

...provide a new origblock 

...on the CNMI queue 

...the first RU 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



V 
V 

V 
V 



V 

*/ 



V 
V 
V 
V 
V 
V 
V 
V 
V 
7 
V 

*/ 

V 

*/ 

V 
V 
7 
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DO WHILE(HLBRC=CNM GOOD); 


/* End of queue reached? 


7 


CALL CNMSMSG(HLBPTR, 


/* Send info to the operator... 


7 


DATAIN, 


/* ...from here 


7 


'MSG', 


/* ...issue message 


7 


'TASK', 


/* ...to the task 


7 


ORIGIN ->ORIG TASK); /* ...that originated request*/ 


CALL CNMGETD(HLBPTR, 


/* Read in the next RU returned 


7 


'GETLINE', 


/* ...a single RU 


7 


DATAIN, 


/* ...into here 


7 


1024, 


/* ...truncate after 1024-bytes 


7 


GETBLOCK, 


/* ...provide a new origblock 


7 


CNMIQ, 


/* ...on the CNMI queue 


7 


l); 


/* ...the next RU 


7 


END; 


/* of DO WHILE 


7 


END; 


/* Of everything ok 


7 


ELSE 






DO; 


/* CNMI error 


7 


SELECT (HLBRC); 






WHEN(CNM BAD INVOCATION) 


/* Not invoked under a DST 


7 


CALL CNMSMSG(HLBPTR,'Must run under a DST', 




'MSG',' TASK' .ORIGIN ->ORIG TASK); 





WHEN(CNM_BAD_TIMEOUT) /* PU never answered request*/ 

CALL CNMSMSG(HLBPTR,'PU never answered', 
'MSG',' TASK", ORIGIN ->0RIGJASK) ; 

WHEN(CNM_NEG_RESPONSE) /* PU gave a negative response*/ 

CALL CNMSMSG(HLBPTR,'PU gave a negative response', 
'MSG' , 'TASK' .ORIGIN ->0RIG_TASK) ; 
OTHERWISE 
CALL CNMSMSG(HLBPTR,'CNMI request failed RC=" || 

CHAR(HLBRC) , 'MSG' , 'TASK' ,0RIGIN->0RIG TASK) ; 

END; /* Of Select ~ */ 

END; /* of CNMI error */ 

END; /* of Good so far */ 

HLBRC=RCODE; /* Issue re */ 
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VSAM (Keyed File Access) 

The following is an example of coding a Netview hll command processor that 
allows i/o to a vsam file through the cnmkio service routine. 

The command processor must execute on a dst. Use either the cnmsmsg service 
routine (with a type of command) or the excmd command. 

This example will create a data base that contains 5 records with the following 
keys and data: 



KEY 


DATA 


01 


A 


02 


B 


03 


C 


04 


D 


05 


E 



DCL REC CHAR(10) VAR; 

DCL INREC CHAR(10) VAR; 

DCL KEY CHAR(2) VAR; 

DCL 0UTDATA(5) CHAR(8) VAR INIT( 

'A' 'B' 'C 'D' 'E')* 

DCL KEYDATA(5) CHAR(2) VAR INIT( 

•eiVOZVGS'.Wt'OS'); 



/* Record that is output 


V 


/* Input record 


V 


/* Key to record 


*/ 


/* Data 


7 



/* Keys 



•♦♦••a**************************************************************. 



/ 

/* 

/* 

/* 

/* 

/* 

/* 

/* 



Execution — 



WRITE OUT 5 RECORDS... 



Put Direct must be used for new records, and put update must 
be used for existing records. Therefore, we use GET equal 
to determine if the record is new or not. If new, then a Put 
Direct will follow... if not, then a put update follows 



*/ 

*/ 

V 
V 

*/ 

V 
V 



/********************************************************************, 



DO I = 1 TO HB0UND(0UTDATA,1); 
KEY=KEYDATA(I); 
REC=KEY| |0UTDATA(I); 
CALL CNMKIO(HLBPTR, 
'GET_EQ\ 
INREC, 
10, 
KEY, 

'UPDATE'); 
IF HLBRC=CNM_NOT_FOUND THEN 
DO; 
CALL CNMKIO(HLBPTR, 
'PUT', 
REC, 

0, 

KEY, 

'DIRECT'); 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



/* 
/* 
/* 
/* 
/* 
/* 



For 5 records 
Set key portion of record 
Record must have key first 
Provide HLB pointer... 
requesting a get 
data is in inrec 
10 bytes max input 
key is in key 
this is an update 



Provide HLB pointer... 
requesting a put 
data is in rec 
not used 
key is in key 
this is not an update 



*/ 

V 
V 
V 
V 
V 
V 
V 
V 



*/ 

V 
V 
V 
V 
V 
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V 

7 
7 
V 



IF HLBRC-*CNM_G00D THEM 
CALL CNMSMSG(HLBPTR, /* Issue error message... 

■CNMKEYIO PUT REQUEST FAILED, RC=' | |CHAR(HLBRC), 

/* . . . text of message 
'MSG', /* ... single line message 

'TASK', /* ... to the task 
0RIGIN->0RIG BLOCK.ORIG TASK); /* ...that invoked*/ 
END; 
ELSE 
CALL CNMKIO(HLBPTR, 
'PUT', 
REC, 
0, 

KEY, 

'UPDATE'); 
IF HLBRC-=CNM GOOD THEN 

/* 



/* 
/* 
/* 
/* 
/* 
/* 



Provide HLB pointer... 


7 


... requesting a put 


7 


... data is in rec 


7 


... not used 


7 


... key is in key 


7 


... this is an update 


7 



CALL CNMSMSG(HLBPTR, 



END; 



Issue error message... 
'CNMKEYIO PUT REQUEST FAILED, RC=' | |CHAR(HLBRC) , 

/* . . . text of message 
'MSG', /* ... single line message 

'TASK', /* ... to the task 
0RIGIN->0RIG_BL0CK.0RIG TASK); /* ...that invoked */ 



7 

7 
7 
7 



fie******************************************************************* 



I 



READ IN THE 5 RECORDS... 



(********************************************************************, 



DO I = 1 TO HB0UND(0UTDATA,1); 
KEY=KEYDATA(I); 
CALL CNMKIO(HLBPTR, 
'GET_EQ\ 
INREC, 

10, 
KEY, 

'NOUPDATE'); 
IF HLBRC-=CNM_G00D THEN 
CALL CNMSMSG(HLBPTR, 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 

/* 



For 5 records 
Set key portion of record 
Provide HLB pointer... 
requesting a get 
data is in inrec 
10 bytes max input 
key is in key 
this is not an update 



*/ 
*/ 

7 

*/ 

V 

*/ 

V 
V 



Issue error message... */ 
•CNMKEYIO GET REQUEST FAILED, RC=' | ICHAR(HLBRC), 

/* ... text of message */ 

'MSG 1 , /* ... single line message */ 

'TASK', /* ... to the task */ 

0RIGIN->0RIG_BL0CK.0RIG_TASK); /* ...that invoked*/ 



END; 



HLBRC=CNM_G00D; 



/* Issue clean re 
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DST User Exit 



The following is an example of coding a Netview hll user exit routine that primes 
an empty vsam data base for a dst. If a vsam data base has not been primed (has at 
least one record), subsequent t/o requests will fail. 

PPRMVDB: PROC(HLBPTR, CMDBUF, ORIGBLCK) 0PTI0NS(MAIN, REENTRANT); 

/* 7 

/* Descriptive Name: High Level Language PL/I DSIXITVN Example */ 
/* 7 



/* Change Activity: */ 

/* date, author: description of changes */ 

/* 7 

/****************************************************************** 

/* 7 

/* Parameter Declarations */ 

/* 7 
/•it************************************************************** 

DCL HLBPTR PTR; /* Pointer to the HLB */ 

%INCLUDE DSIPLI; /* Include the HLL macros */ 

DCL CMDBUF CHAR(*) VARYING; /* Buffer for the command */ 

DCL ORIGBLCK CHAR(40); /* Area for the Orig Block */ 

DCL ORIGIN PTR; /* Pointer to the Orig Block */ 

DCL ADDR BUILTIN; /* Bui 1 tin function */ 

ORIGIN=ADDR(ORIGBLCK); /* Address the Orig Block */ 

/•*************************************************************** 

/* 7 

/* Other Declarations */ 

/* 7 

/••A**************************************************************** 

DCL KEY CHAR (2) VAR; /* 2 byte key of the record */ 

/* 7 

/* Execution - */ 

/* 7 

/* Create the record to initialize the VSAM data base. The */ 

/* record will have a key of 0000 and a value of "Low rec". */ 

/* Setting the HLBRC to USERSWAP (8) will cause the contents */ 

/* of CMDBUF to be swapped into the database, thereby giving */ 

/* it an initial value, and enabling the subsequent VSAM I/O. */ 

/* 7 
/********************************************************************/ 

KEY='0000'X; /* Set key to low values */ 

CMDBUF=KEY||'Low rec'; /* Build the data record */ 

HLBRC=USERSWAP; /* Set USERSWAP re */ 

END PPRMVDB; 
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User Exit 



The following is an example of coding a user exit routine dsiexo3 that sets a task 
global variable equal to the last time a command was entered on the system. If the 
last command was the psnddat command, the task global variable will not be set. 
The psnddat command (see "SEND Side" on page 75) is used to interrogate the 
variable value. 

PSETTG: PROC(HLBPTR,CMDBUF,ORIGBLCK) OPTIONS (MAIN, REENTRANT); 

/••A********************************************************** 

/* 7 

/* Descriptive Name: High Level Language PL/I DSIEX03 Example */ 



/* Change Activity: */ 

/* date, author: description of changes */ 

/* V 
/•••••A********************************************************* 

/* */ 

/* Parameter Declarations */ 

/* */ 

DCL HLBPTR PTR; /* Pointer to the HLB */ 

%INCLUDE DSIPLI; /* Include the HLL macros */ 

DCL CMDBUF CHAR(*) VARYING; /* Buffer for the command */ 

DCL ORIGBLCK CHAR(40); /* Area for the Orig Block */ 

DCL ORIGIN PTR; /* Pointer to the Orig Block */ 

DCL ADDR BUILTIN; /* Bui 1 tin function */ 

ORIGIN=ADDR(ORIGBLCK); /* Address the Orig Block */ 

/•••••••a**************************************** 

/* */ 

/* Other Declarations */ 

/* 7 

DCL TIME CHAR(256) VAR; /* Time last command entered */ 

/* 7 

/* Execution */ 

/* */ 

IF INDEX(CMDBUF,' PSNDDAT' )-=l THEN /* Command other than PSNDDAT? */ 

DO; /* Yes... */ 

CNMINFOC /* Gather Netview information... */ 

ITEM('TIME') /* ...what time is it? */ 

DATA(TIME) /* ...answer goes here */ 

LENG(256); /* ...length of time */ 

CNMVARPOOL FUNC('PUT') /* Put answer in task global... */ 

NAME('LAST_COMMAND_TIME') /* ...by the name of... */ 

POOL('TGLOBAL') /* ...task global pool */ 

DATA(TIME); /* ...information in TIME */ 

END; 

HLBRC=USERASIS; /* Clear RC */ 

END PSETTG; 
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Wait for Data 
WAIT Side 



The following is part of an example of sending messages with a type of request, 
waiting on the response, and parsing the results. 

The purpose of the example is to find the last time that a command was entered on 
the given ost. A task global variable, last_command_time is set by dsiexo3, (see 
"User Exit" on page 72) and this value is retrieved by the psnddat command(see 
"SEND Side" on page 75) that is invoked on the target task. The code in this 
example is the pwatdat command. 

The syntax of the command is: 

PWATDAT taskname 

The flow of the wait for data function is: 



OST 

Invokes 

PWATDAT command 
and specifies the 
target task to 
send the request 



TARGET 
OST 



PWATDAT using 
CNMSMSG sends a 
request to the 
OST specified 

OST issues a WAIT 
FOR DATA 



> 



PSNDDAT command is 
invoked on the 
OST. It finds the 
task global variable 
set by DSIEX03. 



CNMSMSG type of 
< — DATA is invoked with 
the value retrieved 



OST wait is 
satisfied — wake up 
and issue message 
to the operator 
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/********************************************************************; 



Other Declarations 



/* 
/* 

/* 7 



7 
7 



DCL GETBLOCK CHAR(40) , 

NEWMS6 CHAR (256) VAR, 
TARGTASK CHAR (8) VAR, 
TARGTASKF CHAR (8) ; 

DCL PARMCNT FIXED BIN(31); 



/* 
/* 
/* 
/* 
/* 



Area for the Orig Block 
Message sent from PSNDDAT 
Task of inquiry 
Task of inquiry 
Number of parms scanned 



7 
7 
7 
7 
7 



/* 7 

/* Execution */ 

/* */ 



CNMSSCAN DATA(CMDBUF) 

FORMAT ('%*S%S') 
COUNT (PARMCNT) 
PI (TARGTASK); 
IF PARMCNT=1 THEN 
DO; 
TARGTASKF=TARGTASK; 
CNMSENDMSG DATA ('PSNDDAT') 
MSGTYPEC REQUEST') 
DESTTYPE('TASK') 
DEST (TARGTASKF); 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



Scan the input command... 

...skip the command 

...number of parms 

...target task 

Was the target task entered? 

Syntax ok... 

Put into fixed length string 

Invoke PSNDDAT command 

...type is request 

...on a task 

...specified by input 



7 
7 
7 
7 
7 
7 
7 
7 

7 

7 

7 



CNMCOMMAND DATA('WAIT 120 SECONDS FOR DATA'); 



IF HLBRC -« CNM DATA ON WAIT THEN 


/* Wait successful 


? */ 


CNMSENDMSG 


/* 


No... 


' */ 




DATA ('Wait for data abnormally ended') /*...text 


V 




MSGTYPEC MSG') 


/* 


...message 


V 




DESTTYPE('OPER'); 


/* 


...to the operator 


V 


ELSE 




/* 


Wait was successful 


V 


DO; 


i 


/* 


Process the results 


V 




CNMGETDATA FUNC('GETMSG') /* 


Read in the response... 


V 




QUEUE (DATAQ) 


/* 


...on the data queue 


V 




DATA(NEWMSG) 


/* 


...read into NEWMSG variabl 


e */ 




LENG(256) 


/* 


...give plenty of room 


*/ 




ORIGIN(GETBLOCK); 


/* 


...provide a different org 


blk*/ 



/* 

/* 



REMOVE PROCESS ID FROM THE BUFFER ! ! ! ! 
First 8 bytes must be removed 



NEWMSG = SUBSTR(NEWMSG,9); 
CNMSENDMSG 

DATA(NEWMSG) 
MSGTYPE('MSG') 
DESTTYPE('OPER'); 
END; 
END; 
ELSE 
CNMSENDMSG 

DATA(' Target task required') 
MSGTYPEC MSG') 
DESTTYPE('OPER'); 



/* 
/* 
/* 
/* 

r 
r 
r 



Inform user... 

...message is in NEWMSG 

...message 

...to the operator 

of process the results 

of Syntax ok 

Target task not entered... 
/* Inform user... 
/* ...Syntax error 
/* ...message 
/* ...to the operator 



V 
V 

V 

*/ 

V 
V 
V 
V 
V 

*/ 

V 

*/ 
*/ 
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SEND Side 



The following is part of an example for sending messages with a type of request, 
waiting on the response, and parsing the results. 

The purpose of the example is to find the last time that a command was entered on 
the given task. A task global variable, last_command_time is set by dsiexo3, (see 
"User Exit" on page 72). This value is retrieved by the psnddat command that is 
invoked by the pwatdat command (see "Wait for Data" on page 73) on the target 
task. This command processor is executed when the psnddat command is entered. 

/* 7 

/* Other Declarations */ 

/* 7 

DCL TIME CHAR(256) VAR; /* Time the last command was 

...entered */ 

DCL MYOPID CHAR (8) VAR; /* Operator ID that we are running 

...under */ 

/* 7 

/* Execution */ 

/* 7 



CNMINFOC 

ITEM('OPID') 
DATA(MYOPID) 
LENG(8); 

IF MY0PID=0RIGIN->0RIG BLOCK. ORIG 



/* Determine my opid... 
/* ...variable is opid 
/* ...put result here 
/* ...truncate after 8 bytes 

TASK THEN /* Command issued ... 
...directly or target task 



7 
7 
7 
7 







...was same as operators task 


7 


CNMSENDMSG 


/* 


Not allowed... 


7 


DATA(' Invalid syntax') 


/*• 


..text of message 


7 


MSGTYPE('MSG') 


/* 


...message is a single line 


7 


DESTTYPE('OPER'); 


/* 


...to a operator 


7 


ELSE 








DO; 








CNMVARPOOL 


/* 


Retrieve last time variable 


7 


FUNC(GET) 


/* 


...read in the value 


7 


NAME ('LAST COMMAND TIME') 




/* ...of the variable 


7 


POOL('TGLOBAL') 


/* 


...in the task global pool 


V 


DATA(TIME) 


/* 


...into time 


7 


LENG(256); 


/* 


...truncate at 256 


7 
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IF (HLBRC=CNM GOOD) THEN /* Variable set? */ 

CNMSENDMSG " /* Yes, continue... */ 

DATA(ORIGIN->ORIG_PROCESS || /* ...must put the process id in*/ 

'Last command entered at : "' | | /* ...text of message */ 

TIMEM"") /* ... more text */ 

MSGTYPE('DATA') /* ...message is data */ 

DESTTYPE('TASK') /* ...to a task */ 

DEST(ORIGIN->ORIG TASK); /* ...that invoked us */ 
ELSE 

CNMSENDMSG /* No, inform user... */ 

DATA(ORIGIN->ORIG_PROCESS || /* ...must put in process id*/ 
'Must install DSIEX03 to set TIME variable OR no ' || 
'command entered yet on that task') 

MSGTYPE('DATA') /* ...message is data */ 

DESTTYPE('TASK') /* ...to a task */ 

DEST(ORIGIN->ORIG_TASK); /* ...that invoked us */ 
END; 
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Chapter 6. Using KnowledgeTool Programs in NetView 

This chapter explains how you can use KnowledgeTool™ Version 2 to provide 
knowledge applications that interact with NetView. 

Detailed guidance for developing knowledge applications can be found in the 
KnowledgeTool Application Development Guide (SH20-9262). 

Knowledge Applications in the NetView Environment 

KnowledgeTool is a pl/i extension and to NetView, a knowledge application is an 
hll command processor. Within the knowledge application, NetView functions can 
be invoked anywhere normal procedural calls can be made — for example, in the 
right-hand side of rules, in on entry blocks, in on idle blocks, and in on cycle 
blocks. Functions that invoke hll services can be used on the left-hand side of 
rules. 

After the hll program has been written according to KnowledgeTool conventions, it 
is compiled and link-edited using commands supplied with KnowledgeTool. The 
ktcomp command puts the program through several compilation steps that produce 
an object file ready for linkage. The ktlink command uses the linkage editor to 
create the application load module using options specified in the knowledge appli- 
cation profile. 

The ktrun command is not used under NetView. Instead, after you specify the 
application load module name as the mod parameter of a cmdmdl statement in the 
dsicmd member of dsiparm, you can invoke the knowledge application like any 
NetView command. 

Applications created with KnowledgeTool Version 2 run as command processors 
under ost, nnt, or Autotasks. Every knowledge application is initialized when it is 
invoked. If the application uses a loop waiting for an event, for example the arrival 
of a message, the initialization overhead can be avoided. 

Sample Knowledge Application 

The following example issues the mapcl command to monitor usage of loaded 
command lists. The following figure shows a display resulting from mapcl. 

^" . ■ ■ . .............. 

i CNM429I MAPCL DISPLAY 

I NAME USAGE RECORDS BYTES DATE TIME DP R/C 



CL1 2 2592 03/30/89 11:26:37 R 

CL2 3 5 5234 03/30/89 11:26:37 R 



|: 2 3 7 7826 -TOTALS— 

If a loaded command list has not been used for 10 or 20 minutes, depending on its 
size, it is dropped. This example is intended to illustrate some capabilities of 
knowledge applications. Message automation could also perform this simple task, 
but using a knowledge application would allow you to include more complex deci- 



™ KnowledgeTool is a trademark of International Business Machines Corporation 
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sions and actions making full use of the expert system technology available with 
KnowledgeTool. 

The profile for this example can be developed by following the instructions in the 
NetView section of KnowledgeTool Application Development Guide (SH20-9262). 

The sample contains the following KnowledgeTool blocks: 

ON ENTRY Run once during the initialization of the rule block. 

ON IDLE Run whenever the conflict set is empty. 

SAMPKT: PR0C(HLBPTR,CMDBUF,0RIGBLCK) 0PTI0NS(MAIN, REENTRANT); 

/•••♦A***************************************************** 

/* */ 

/* Descriptive Name: Sample KnowledgeTool Program */ 

/* */ 

/* Function: */ 

/* Monitor usage of loaded command lists and drop */ 

/* those that are unused */ 

/* IF SIZE> 2,000 bytes drop if idle more than 10 minutes */ 

/* IF SIZE<= 2,000 bytes drop if idle more than 20 minutes */ 

/* */ 

/* Dependencies: None */ 

/* V 

/* Restrictions: None */ 

/* V 

/* Language: PL/I (KT) */ 

/* V 

/* Input: */ 

/* 1) A pointer to a 4-byte field containing the address of */ 

/* the HLB control block. */ 

/* 2) A varying length character string containing the */ 

/* command or message which invoked this program. */ 

/* 3) A 40-byte structure which describes the origin of the */ 

/* request that caused execution of this program. */ 

/* V 

/* Output: None */ 

/* */ 

/* Return Codes: returned in Hlbrc */ 

/* = normal exit */ 

/* */ 

/* External Module References: None */ 
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/* NetView High-Level Language include files */ 

/********************************************************************/ 

%INCLUDE DSIPLI; /* Include the HLL macros */ 

/A*******************************************************************/ 

/* Parameter declarations */ 

/***********************•********************************************/ 

DCL HLBPTR PTR; /* Pointer to the HLB */ 

DCL CMDBUF CHAR(*) VARYING; /* Buffer for the command */ 

DCL ORIGBLCK CHAR(40); /* Area for the Origin Block */ 

/•it************************************************************** 

/* Class declarations */ 

/♦••A****************************************************************/ 

DCL 1 CLIST CLASS, 

2 CLNAME CHAR (8) VARYING, 

2 CLBYTE FIXED BIN(31), 

2 CLCOUNT FIXED BIN(31), 

2 CLTIME FIXED BIN(31), 

2 IDLETIME FIXED BIN(31); 
DCL CL_SEL SELECTOR; 
DCL 1 CTIME CLASS, 

2 CURTIME FIXED BIN(31); 

DCL T SELECTOR; 

/A************************************************************* 

/* Other declarations */ 

DCL 1 ORIGTEMP LIKE ORIGJLOCK; /* ORIGBLOCK for read operations */ 

count for SSCAN service */ 

DO loop control */ 

Use count for SSCAN service */ 

Command list size in bytes */ 

Time of previous MAPCL */ 

Buffer for incoming messages */ 
DCL MAPNAME VARYING CHAR(08); /* Command list name from MAPCL */ 
DCL (SUBSTR,ADDR,TIME, MATCH) BUILTIN; 

/* ON ENTRY Define messages to be trapped */ 

ON ENTRY BEGIN; 

CALL CNMCMD( HLBPTR,' TRAP MESSAGES CNM429I'); 

ALLOCATE CTIME SET (T); 
END; 



/* Command list name 


7 


/* Command list size in bytes 


V 


/* Use Count 


V 


/* Time of last element update 


*/ 


/* Time Command list not in use 


*/ 


/* CLIST selector 


V 


/* Current time in minutes 


V 


/* Time SELECTOR 


*/ 



DCL (C0UNT1, 


/* 


I, 


/* 


MAPCOUNT, 


/* 


MAPBYTE, 


/* 


PREVTIME) 


/* 


FIXED BIN(31); 




DCL MSGBUF VARYING CHAR(80); 


/* 
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/* RULE to cleanup working memory */ 

RUL1: WHEN (CL_SEL=>CLIST & T=>CTIME 

(CL_SEL=>CLTIME -=T=>CURTIME)) BEGIN; 
FREE CL_SEL=>CLIST; 

ENDRUL1: END; 

/A********************************************************* 

/* RULE to drop large Command lists */ 

/••••A**************************************** 

RUL2: WHEN (CL_SEL=>CLIST (CL_SEL=>CLBYTE > 20000, 

CL_SEL=>IDLETIME>10 )) BEGIN; 

CALL CNMCMD (HLBPTR, 'DROPCL ' | |CL_SEL=>CLNAME); 

FREE CL_SEL=>CLIST; 
ENDRUL2: END; 

/* RULE to drop small Command lists */ 

RUL3: WHEN (CL_SEL=>CLIST (CL_SEL=>CLBYTE <= 20000, 

CL_SEL=>IDLETIME>20 )) BEGIN; 

CALL CNMCMD (HLBPTR, 'DROPCL ' | | CL_SEL=>CLNAME) ; 

FREE CL_SEL=>CLIST; 
ENDRUL3: END; 

/* ON IDLE */ 

ON IDLE BEGIN; /* wait for incoming message */ 

CALL CNMCMD (HLBPTR,' WAIT 2 MINUTES FOR MESSAGES'); 
IF HLBRC = CNM_TIME_OUT_WAIT THEN CALL CNMCMD (HLBPTR, 'MAPCL'); 

/* Convert time in CHAR to numeric. Add 24 hours if time wrapped */ 

T=>CURTIME = SUBSTR(TIME(),3,2)+60*SUBSTR(TIME(),1,2); 

IF (T=>CURTIME < PREVTIME) THEN T=>CURTIME = T=>CURTIME + 24*60; 

PREVTIME = T=>CURTIME; 

HLBRC=0; 

DO 1=1 TO 4 WHILE (HLBRC=0) ; /* Read past header records */ 

CNMGETDATA FUNC('GETLINE') DATA(MSGBUF) LENG(80) 

ORIGIN(ORIGTEMP) QUEUE(l); 
END; 
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/* Process to first trailer record */ 

DO WHILE ((HLBRC=0)&(SUBSTR(MSGBUF,l,4h=' ')); 

CNMSSCAN DATA(MSGBUF) /* Parse MAPCL results */ 
FORMAT ('%S%D%*D%D') /* Skip number of records */ 
COUNT(COUNTl) 

Pl(MAPNAME) /* Command list name */ 

P2 (MAPCOUNT) /* Command list use count */ 

P3(MAPBYTE); /* Command list size */ 

IF MATCH (CL_SEL=>CLIST(CL_SEL=>CLNAME=MAPNAME)) THEN DO; 
IF MAPCOUNT=CL_SEL=>CLCOUNT THEN DO;/* Command list was idle 
CL_SEL=>IDLETIME = CL_SEL=>IDLETIME + T=>CURTIME - 
CL_SEL=>CLTIME; 
END; /* END Command list was idle */ 

ELSE DO; /* Command list was used */ 

CL_SEL=>IDLETIME = 0; /* Reset Idle time */ 

CL_SEL=>CLCOUNT = MAPCOUNT;/* Set new use count */ 

END; 
END; /* End match */ 

ELSE DO; /* No match */ 

ALLOCATE CLIST SET(CL_SEL);/* allocate new Command list */ 
CL_SEL=>CLNAME = MAPNAME; 
CL_SEL=>CLBYTE = MAPBYTE; 
CL_SEL=>CLCOUNT = MAPCOUNT; 
CL_SEL=>IDLETIME = 0; 
END; /* End no match */ 

CL_SEL=>CLTIME = T=>CURTIME; 

CNMGETDATA FUNC('GETLINE') /* Read next line of response */ 

DATA(MSGBUF) LENG(80) ORIGIN (ORIGTEMP) QUEUE(l); 

END; /* end Do while */ 

CNMGETDATA FUNC('FLUSHQ') QUEUE (1); /* Flush trailer records */ 

END; /* End ON IDLE */ 

END; /* End Procedure */ 



Developing Knowledge Applications 

Information on developing knowledge applications is given in the KnowledgeTool 
Application Development Guide. To use the KnowledgeTool debugger under 
NetView you must provide the appropriate system extensions. 

There are three system extensions (sometimes called knowledge routines) that 
control input and output when using the KnowledgeTool debugger (in line mode, as 
required under NetView). These are called stdin, stdout, and stderr, but they are 
also known by their internal names as ewccsino, ewccsouo, and ewccmdso respec- 
tively. The person who manages the NetView environment must change the 
content of these system extensions, so they direct input, output, and messages to 
the correct destinations for NetView. The sample system extensions that follow 
can be compiled by pl/i with a compile syslib for the Netview Maclib. Compiler 
options of include and macro should be specified. Unlike NetView applications, 
extensions should not include dsiexkt or dsihstub when they are linked by ktlink. 
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Example of Standard Input System Extension 

This example defines NetView operator terminal as a standard input device, stdin. 



♦PROCESS MARGINS (2, 72); 

/••••••A*************************************************************/ 

Descriptive Name: Standard Input System Extension 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/ 



Function: 

Defines NetView operator terminal as a standard input 
device, STDIN. 

Dependencies: None 
Restrictions: None 

Language: PL/I 

Input: None 

Output: None 

Return Codes: returned in HLBRC 
= normal exit 

External Module References: None 

******************************************************** 



7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
/ 



%INCLUDE EWCDPLIO; 
INVOKED_KR(EWCCSIN,IPARM,OPARM) ; 
%INCLUDE DSIPLI; 



/* Frame definitions 
/* STDIN Knowledge Routine 

/* HLL control blks & macros*/ 



7 
7 



DCL IPARM POINTER; 

DCL (STG.UNSPEC) BUILTIN; 

DCL OPARM FIXED BIN(31); 

DCL IBUF CHAR(512) BASED(IPARM); 

DCL ISTRING CHAR(511) VARYING; 

DCL 1 IORIGIN LIKE 0RIG_BL0CK; 

DCL NULLJUM FIXED BIN(8) INIT(O); 
DCL NULL_CHAR CHAR; 



/* Ptr to buffer pointer */ 



/* Return code 
/* Input buffer 

/* Control block for input 
services 

/* Null string 



7 
7 



7 
7 



DCL HLBPTR PTR; 

DCL HLBPTR_MAP PTR BASED; 
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UNSPEC(NULL_CHAR)=UNSPEC(NULLJUM);/* Initialize null string */ 

INIT_FS(KR); " /* Initialize enviornment */ 

HLBPTR=EWCDPARM_PTR->HLBPTR_MAP /* Extract HLBPTR for use by */ 

->HLBPTR_MAP->HLBPTR_MAP; /* CNM... commands */ 

CALL CNMSMSG (HLBPTR, /* Display prompt message */ 

1 ENTER KNOWLEDGETOOL COMMAND: (GO XXX) ' , 'MSG' , 'OPER' , " ) ; 

CALL CNMCMD (HLBPTR,' WAIT FOR OPINPUT'); /* Wait for operator input */ 

CALL CNMGETD(HLBPTR,'GETLINE',ISTRING, /* Get operator input */ 

STG(ISTRING)-2,I0RIGIN,2,0); 

IF HLBRC = THEN /* Test GET return code */ 

DO; /* Get Successful */ 

IBUF=ISTRING| | NULL CHAR; /*Place oper input in buffer */ 

CALL CNMSMSG (HLBPTR,'— >' | } ISTRING, /* Echo input */ 

•MSG', 'OPER',"); 

OPARM=0; /* Set return code */ 

END; 
ELSE 

DO; /* Get unsuccessful */ 

IBUF=NULL_CHAR; /* Set Buffer to null string */ 

0PARM=0; ~ /* Set Return code */ 

END; 

END EWCCSIN; 
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Example of Standard Output System Extension 

This example defines NetView operator terminal as a standard output device, 

STDOUT. 

♦PROCESS MARGINS(2, 72), SOURCE, INSOURCE; 

/* Descriptive Name: Standard Output System Extension */ 

/* */ 

/* 7 

/* Function: */ 

/* Defines NetView operator terminal as a standard output */ 

/* device, STDOUT */ 

/* 7 

/* Dependencies: None */ 

/* Restrictions: None */ 

/* 7 

/* Language: PL/I */ 

/* 7 

/* Input: None */ 

/* 7 

/* Output: None */ 

/* 7 

/* Return Codes: returned in HLBRC */ 

/* = normal exit */ 

/* */ 

/* External Module References: None */ 

/* 7 

%INCLUDE EWCDPLIO; /* Frame Definitions */ 

INVOKED_KR(EWCCSOU,IPARM,OPARM); /* STDOUT Knowledge Routine */ 
%INCLUDE DSIPLI; /* HLL control biks & macros*/ 

DCL STR CHAR(256) VARYING; 

DCL IPARM POINTER; /* ptr to input buffer */ 

DCL OPARM POINTER; /* dummy pointer */ 

DCL IBUF CHAR(256) BASED(IPARM); /* input buffer */ 

DCL NULL NUM FIXED BIN(8) INIT(G); /* used to init null char */ 

DCL NULL CHAR CHAR; /* null character */ 

DCL (INDEX, MIN,SUBSTR,UNSPEC) BUILTIN; 

DCL HLBPTR PTR; 

DCL HLBPTR_MAP PTR BASED; 

INIT FS(KR); /* initialize enviornment */ 

UNSPEC(NULL_CHAR)=UNSPEC(NULLJUM);/* initialize null character */ 

STR=SUBSTR(IBUF,1,MIN(256, *" /* extract msg from IBUF */ 
INDEX(IBUF,NULL_CHAR)-1)); 

HLBPTR=EWCDPARM_PTR->HLBPTR MAP /* extract HLBPTR for use by */ 

->HLBPTR_MAP->HLBPTR_MAP; " /* CNMSENDMSG */ 
CALL CNMSMSGCHLBPTR.STR/MSG'.'OPER',' '); /* send msg to operator */ 

END EWCCSOU; 
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Example of Standard Error System Extension 

This example defines NetView operator terminal as a standard error device, 

STDERR. 

♦PROCESS MARGINS (2, 72); 

/**************************•************************************* 

/* Descriptive Name: Standard error System Extension */ 

/* V 

/* */ 

/*■ Function: */ 

/* Defines NetView operator terminal as a standard error */ 

/* device, STDERR */ 

/* */ 

/* Dependencies: None */ 

/* Restrictions: None */ 

/* V 

/* Language: PL/I */ 

/* V 

/* Input: None */ 

/* V 

/* Output: None */ 

/* V 

/* Return Codes: returned in HLBRC */ 

/* = normal exit */ 

/* V 

/* External Module References: None */ 

/* V 

%INCLUDE EWCDPLIO; /* frame definitions */ 

INVOKED_KR(EWCCMDS,IPARM,OPARM); /* STDERR Knowledge routine */ 
%INCLUDE DSIPLI; /* HLL control blks & macros*/ 

DCL STR CHAR(256) VARYING; 

DCL IPARM POINTER; /* ptr to input buffer */ 

DCL OPARM POINTER; /* dummy pointer */ 

DCL IBUF CHAR(256) BASED(IPARM); /* input buffer */ 

DCL NULLJUM FIXED BIN(8) INIT(0); /* used to init null char */ 

DCL NULL_CHAR CHAR; /* null character */ 

DCL (INDEX, MIN S SUBSTR,UNSPEC) BUILTIN; 

DCL HLBPTR PTR; 

DCL HLBPTR_MAP PTR BASED; 

INIT_FS(KR); /* initialize enviornment */ 

UNSPEC(NULL_CHAR)=UNSPEC(NULL_NUM);/*initialize null character */ 

STR=SUBSTR(IBUF,1,MIN(256, /* extract msg from IBUF */ 

INDEX(IBUF,NULL_CHAR)-1)); 

HLBPTR=EWCDPARM PTR->HLBPTR_MAP /* extract HLBPTR for use by */ 

->HLBPTR_MAP->HLBPTR_MAP; /* CNMSENDMSG */ 
CALL CNMSMSG (HLBPTR, STR,' MSG' ,'OPER' ,"); /* send msg to operator */ 
END EWCCMDS; 
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Chapter 7. 
Program 



Compiling, Link-Editing, and Running Your PL/I 



Once you have a pl/i compiler installed, you can modify the pl/i compile and link- 
edit jcl for use with NetView. The objective of this chapter is to provide the infor- 
mation necessary to make these modifications. 

Several examples of compile and link-edit jcl will be provided in this chapter. 
These are given as examples only. You are responsible for modifying the compile 
and link-edit jcl samples that were shipped with the pl/i compiler. 

You must have completed the installation steps for hll as described in the NetView 
Installation and Administration Guide before attempting to execute pl/i programs in 
the NetView environment. 



Compiling 



In order to compile pl/i programs using NetView services, it is necessary to modify 
the compile step in the jcl to reference the NetView macro library(s). You will 
need to include in the compiled jcl a syslib statement for syslmaclib. An example 
of modifications to the compile step jcl is shown below. 

//COMPILE EXEC PGM=IEL0AA,REGI0N=1000K, 
// PARM=' OBJECT, MACRO, LI ST' 



//SYSLIB DD DSN=SYS1.MACLIB,DISP=SHR 



Note: When you are compiling pl/i programs, you will receive a warning message 
IEL0548I. This message should be ignored. 



Link-editing 



The following rules apply when link-editing pl/i modules: 

• All pl/i load modules must be reentrant. 

• pl/i load modules can reside in 24 or 31 bit storage and can be entered in 
either addressing mode. 

• All pl/i load modules must be link-edited with dsihstub and dsiexpli. dsihstub 
must be the entry point. For KnowledgeTool applications, dsiexpli should be 
replaced by dsiexkt. 

In order to link-edit a pl/i module to run with NetView, you must modify the pl/i link- 
edit step in the jcl to reference the appropriate NetView Library(s). This will allow 
you to include dsihstub and dsiexpli at link-edit time. Add sysllinklib to the list of 
automatic call libraries already defined by syslib in the pl/i link-edit step of the jcl. 
An example is shown below: 
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Running 



//LKED EXEC PGM=IEWL, 

// PARM='XREF, RENT, LET, LIST,AMODE=&AMODE, RMODE=&RMODE ' , 

// REGI0N=4096K,C0ND=(8,LE, COMPILE) 



// DD DSN=SYS1.PLIBASE,DISP=SHR 

//SYSLIB DO DSN=SYS1.LINKLIB,DISP=SHR 



INCLUDE 


SYSLIB(DSIHSTUB) 


INCLUDE 


SYSLIB(DSIEXPLI) 


ORDER 


DSIHSTUB 


ENTRY 


DSIHSTUB 


MODE 


AMODE(31),RMODE(ANY) 


NAME 


LMODNAME(R) 



Note: All hll modules must be compiled and link-edited with the reentrant option. 
For pl/i, you will have to include the reentrant option on the pl/i procedure state- 
ment. The resulting object deck(s) must then be link-edited with the rent option. 



A set of run-time libraries will be shipped with the compiler. In order to execute a 
pl/i program in the NetView environment, you must modify your NetView start up 
procedure to reference the appropriate pl/i run-time libraries. Refer to the NetView 
Installation and Administration Guide for more information. 

hll command processors require a cmdmdl statement in member dsicmd of the 
dsiparm dataset. User exits are loaded at initialization and need to conform to user 
exit naming conventions. For more information on user exits see Chapter 2 on 
page 9. 
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Chapter 8. Coding Your C Program - Interfaces and 
Restrictions 

This chapter will provide necessary information for coding hll command 
processors and user exits in c. The appropriate interfaces and language 
dependent restrictions will also be discussed. 

Initial Parameters 

Every hll program written in c must have exactly one function main that declares 
the parameters argc and argv. The first parameter, argc, is an integer value that 
indicates the number of pointers in the array argv. argc is not used by NetView. 
argv is an array of pointers. In the normal c environment, each element in argv 
points to an argument in the command line. In the NetView environment, elements 
one through three point to the ebcdic representation of the initial parameters 
{Hlbptr, Cmdbuf and Origblck) passed to main from NetView. The initial parame- 
ters must be converted to hex using sscanf. The original command line will be 
passed to the user's program in Cmdbuf. Chapter 9 contains a sample template 
for coding the main function and defining and converting the initial parameters. 
The descriptions of the initial parameters are as follows: 

Hlbptr 

A 4-byte pointer field containing the address of the hlb control block (dsichlb). 
The hlb control block is the hll api interface block that is used to communicate 
between the hll service routines and hll programs in the NetView environ- 
ment. This pointer is required on all hll service routine invocations. 

Cmdbuf 

A pointer to a varying length character string that contains the command or 
message that drove this program. 

If this program was driven as a user exit (other than dsiexo2A), this string con- 
tains the message which drove this exit. If driven as dsexo2a, Cmdbuf will not 
contain any useful information. The user will have to retrieve the message 
from the Initial Data Queue (idataq). 

Origblck 

A pointer to a 40-byte structure which describes the origin of the request that 
caused execution of this program. Origblck is mapped by dsicorig. 

LL Run-Time Options 

hll run-time options can be specified by declaring and initializing the external vari- 
able named hllopts. If the user does not code hll run-time options, the default hll 
run-time options are assumed. The default value for hllopts is zero. The following 
bits are defined in hllopts: 
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Bit 

Position Field Name Description 

HLL_QUEUED_INPUT Determines if an hll program will accept 

QUEUEd input. Refer to the queue command 
in the NetView Operation manual for further 
detail. 

= hll program will NOT accept QUEUEd 
input 

1 = hll program will accept QUEUEd input 

1 HLL_NO_CANCEL Determines if an hll program will terminate 

on cancel/reset. Refer to reset command 
in the NetView Operation manual for further 
detail. 

= Cancellable 

1 = Non-cancellable 

2-31 reserved for internal use. Do not assign 

any values to these fields. 

The following example illustrates how the default hll run-time options can be over- 
ridden in an hll program written in c. In this case, the user has chosen to make 
this c program non-cancellable. 

#pragma variable(HLLOPTS,NORENT) 

extern unsigned int HLLOPTS = 0X40000000; 

The ftpragma variable preprocessor directive shown above indicates that the vari- 
able named hllopts is to be used in a non-reentrant fashion. This does not have 
any effect on the reentrancy of the hll program. 

C Run-time Options 

The run-time options for a c program can be specified using the following pre- 
processor directive. Refer to the C/370 User's Guide for a detailed explanation of 
each of the options. The run-time options for executing c programs in the NetView 
environment are shown in the c coding template provided in Chapter 9. c pro- 
grams must run with the nostae and nospie options when running in the NetView 
environment. Running with the stae or spie options will cause unpredictable 
results in cases where error recovery is necessary. 

#pragma runop.ts (N0EXEC0PS, NOSTAE, NOSPIE, ISASIZE(4K),ISAINC(4K)) 

To achieve optimum performance, it is recommended to run with the report option 
until accurate isa and heap sizes are determined. Refer to the run-time storage 
section of the C/370 User's Guide for further details. 

Parameters Passed to HLL Service Routines 

There are four different types of parameters that can be passed to hll service rou- 
tines. Each of the parameters described throughout Chapter 12 fall into one of 
these categories: 

Pointer Variables 

Integer Variables 

Fixed Length Character Strings 

Varying Length Character Strings 
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A discussion of each of these parameter types follows. The intent of this section is 
to describe how each of these parameter types can be declared, initialized and 
passed to the hll service routines. Examples and recommendations for writing hll 
programs in c have been provided in this chapter. Note that these examples are 
not complete. They have been included here to emphasize how the hll service 
routine parameters should be declared, initialized and passed. For complete 
examples of user written hll programs, see the hll samples shipped with NetView. 
(See Appendix D on page 295.) 

Pointer Variables 

A pointer variable is a 4-byte pointer field containing an address. All hll service 
routines require at least one argument of this type, Hlbptr. Hlbptr is required for all 
hll service routine invocations. The value of Hlbptr is calculated by NetView and 
passed to the hll command processor or user exit. Therefore, it only needs to be 
defined in c. The user should NEVER assign a value to this variable. This is the 
only parameter of this type which does not have to be assigned by the user. 

Note: The user does not need to specify the Hlbptr parameter when coding the hll 
service routine invocations in c. Hlbptr is inserted for the user before the hll 
service routine is actually invoked. 

If an hll service routine is expecting an address in a pointer field, the user is 
responsible for assigning a value to that pointer field before invoking the hll 
service routine. Hlbptr is the only exception to this rule. For c, it is advised to use 
the & (address) operator when passing pointer variables to hll service routines 
rather than creating a separate pointer variable for this purpose. This will ensure 
that the pointer variable has been assigned a value before invoking the hll service 
routine. 
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#define VARTOVAR 
Dsihlb *Hlbptr; 
Dsivarch *srcptr; 
Dsivarch *dstptr; 

Qj int dstlen; 

B Dsivarch srcbuf; 
Dsivarch dstbuf; 

M srcptr = &srcbuf ; 
3 dstptr = &dstbuf ; 



3 dstlen = 255; 



"VARTOVAR" 



7 
7 



/* VARTOVAR constant 

/* HLB pointer MUST BE DEFINED 

/* Pointer to source buffer */ 

/* Pointer to destination buffer */ 

/* Length of destination buffer */ 



/* Source buffer 

/* Destination buffer 



7 
7 



/* Address of source buffer */ 

/* Address of destination buffer */ 



Cnmcpys( srcptr, dstptr, dstlen, VARTOVAR); /* Copy buffer 
Figure 3. Using Pointer Variables in C 






Hlbptr is defined as a pointer variable. The user does not need to assign a 
value to Hlbptr or include it in the Cnmcpys invocation. The value of Hlbptr is 
calculated by NetView and inserted in the parameter list for the user during the 
preprocessor phase of the compilation. 



srcptr is defined as a pointer to a structure of type Dsivarch (varying length 
character string). 



srcptr is assigned the address of the source buffer (srcbuf) to be used as a 
parameter to Cnmcpys. 

I 

srcptr is passed as a parameter to Cnmcpys. 

Replacing Q with the following step illustrates the use of the & (address) 
operator in c. Use of this operator will eliminate the need to define pointer var- 
iables and is advisable whenever possible. Note the use of a string constant 
instead of the vartovar constant. 



Cnmcpys (&srcbuf,&dstbuf, dstlen, "VARTOVAR"); /* Copy buffer 



7 
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Integer Variables 



Several of the hll service routines require the user to pass a 4-byte integer value 
to be used as a length, count, queue number, etc.. Figure 4 illustrates the use of 
integer variables in the hll environment. 



struct Vcharl2 { 
short int size; 
char buffer [13]; 
}; 



Dsihlb *Hlbptr 
Vcharl2 spname; 
char spfunc[9]; 
int sptoken; 
int spleng; 
int sppricnt; 
int spseccnt; 
int spclass; 



spfunc = "ALLOC "; 
Cnmvlc(&spname,NOHEXCNV,"POOLNAME"); / 



sptoken 

spleng 

sppricnt 

spseccnt 

spclass 



0; 

256; 

3; 

2 

1 



/* Size of buffer 


V 


/* Text buffer 


V 


/* HLB pointer MUST BE DEFINED 


*/ 


/* Subpool name 


*/ 


/* Subpool function 


*/ 


/* Subpool token (returned) 


V 


/* Cell size 


*/ 


/* Number of cells in primary 


V 


/* Number of cells in secondary 


*/ 


/* Class of storage 


*/ 


/* Function is ALLOCATE 


*/ 


"); /* Initialize subpool name 


*/ 


/* Initialize subpool token 


V 


/* Cell size = 256 bytes 


V 


/* Primary count = 3 


V 


/* Secondary count = 2 


*/ 


/* Class = 31 bit addressable 


*/ 



JHI Cnmpool (spfunc, &sptoken,&spname, spleng, sppricnt, spseccnt, 
spclass); /* Allocate Subpool 

Figure 4. Using Integer Variables in C 



sptoken is defined as a 4-byte integer (int). 



spleng is defined as a 4-byte integer (int). 



sptoken is initialized to zero. A value will be returned in sptoken upon suc- 
cessful completion of the Cnmpool invocation. 

[ 

spleng is assigned a value of 256 to be used in the call to Cnmpool. 



Cnmpool is invoked using &sptoken and spleng as parameters. The value of 
sptoken will be returned to the user upon successful completion of the 
Cnmpool service. 

Note: All of the integer variables are specified by name except for sptoken. 
sptoken is specified using the & (address) operator. In c, all parameter fields 
that return values to the the user's program must specify a pointer to that 
parameter field when invoking an hll service routine. Otherwise, the user will 
not see the changes made to that variable upon successful completion of the 
hll service routine. Using the & (address) operator ensures that the value is 
returned to the calling program. 
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The & (address) operator is also used for spname. This is explained in detail 
in the section on varying length character strings. 

Fixed Length Character Strings 

The majority of the hll service routines require the user to pass one or more fixed 
length character strings as arguments. Most of these fixed length character 
strings, except adorigln and gdorigin, are eight characters long. These exceptions 
are discussed below. 

c string constants for most of the fixed length character strings have been provided 
in dsiccons. dsiccons is optional and can be tailored to the specific needs of the 
user. The following steps correlate to the steps in Figure 4 on page 95. 



spfunc is defined as a 9-byte character array (8 bytes + \0 character). 

spfunc is assigned a value of "ALLOC " to be used in the Cnmpool invocation. 

Cnmpool is invoked using the spfunc parameter, spfunc could have been 
defined with a preprocessor define statement (see vartovar in Figure 3 step 
3 ), or passed as a string constant. 

Cnmpool ( "ALLOC " ,&sptoken , &spname , spl eng , sppri cnt , spseccnt , 

spclass); /* Allocate Subpool */ 

c does not pad character strings with blanks. It is the responsibility of the user to 
pad character strings with blanks. 

Also, all character strings must be delimited by the null character (\0) which is the 
'end of string' character in c. Enclosing text in double quotes will ensure that the 
null character is appended to the last byte of the character string. As a result, 
when using a character array to represent a fixed length character string, the user 
must define the character array's length to be 1 character greater than the length 
expected by the hll service routine. The use of character arrays to represent fixed 
length character strings should be avoided whenever possible. Any of the alterna- 
tive methods mentioned above can be used to ensure that the fixed length char- 
acter string is padded with blanks and delimited by the null character (\0). For 
further explanation, refer to the c documentation. 

The only fixed length character fields required for hll services that are not 8 bytes 
in length are origin blocks. The mapping structure for an origin block resides in 
file dsicorig which is included by dsic. 

There are two types of origin blocks used by the hll service routines. The first 
type of origin block {Origblck) is a 40-byte structure which must be declared by the 
user. This is a required initial parameter which was previously described in 'Initial 
Parameter' section of this chapter. The user is responsible for defining this 40-byte 
structure but should never need to alter it. Refer to the c coding template in 
Chapter 9 on page 107 for an example of how to define Origblck. 

The second type of origin block {adorigin, gdorigin) is specified by the user. 
adorigin and gdorigin must be at least 38 bytes long and must map to the first 38 
bytes of the origin block structure (dsicorig). The user MUST define these origin 
blocks separately from the origin block which is required as an initial parameter. 
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The initial parameter origin block (Origblck) should NOT be used in place of 
adorigin or gdorigin. 

Varying Length Character Strings 

Several of the hll service routines require the user to pass a varying length char- 
acter string as an argument. Varying length character strings are currently sup- 
ported in the pl/i environment but not in c. As a result, a structure must be defined 
to map the internal representation of a varying length character string as shown 
below. 

1 : .IL | TEXT ' ~ ".' 

Where: 

LL 2-byte integer field containing the length of text 

TEXT the character string 

Dsivarch is an example of a structure that maps a varying length character string. 
The maximum size of the buffer portion of this particular structure is 256 bytes; 255 
bytes (maximum) of text plus one byte for the end of string character (\0). Dsivarch 
resides in dsicvarc and is included by dsic. The structure consists of two parts: 

size A 2-byte (short) integer field which contains the size of the character 

array represented by buffer. The end of string character (\0) is not 
included in this size but should delimit the character array. 

buffer A 255-byte null-terminated (delimited by the end of string character 

(\0)) character array. 

The user is responsible for creating structures like Dsivarch to represent varying 
length character strings to be passed to hll service routines. The size portion of 
the buffer can be used to manipulate buffers that contain hex data. The presence 
of the null character at the end of the buffer enables the user to use the buffer 
portion of the structure in other c functions that require the end of string character 
as a delimiter. The user is responsible for ensuring that the end of string character 
delimits the buffer portion of the structure when necessary. 

Note: hll service routines that return data in varying length character strings do 
not delimit the data with the end of string character. 

NetView has provided two functions to enable the user to easily manipulate varying 
length character strings in the c environment. Cnmvlc and Cnmnvlc calculate the 
value of the 2-byte size field and ensure that the buffer portion of the varying length 
character string is delimited by the end of string character (\0). These are the 
ONLY functions that should be used when initializing or altering the buffer portion 
of a varying length character string. If the user chooses to alter the contents of a 
varying length character string without using Cnmvlc or Cnmnvlc, they are respon- 
sible for updating the size field and ensuring that the buffer is null-terminated. 
Cnmnvlc and Cnmvlc are described in this chapter because they are specific to c 
support only. 

The following steps correlate to the steps in Figure 4 on page 95. 
spname is defined as a varying length character string. 
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EO 

spname is assigned the value poolname using the Cnmvlc function. 

m 

Cnmpool is invoked with the parameter Aspname. When passing a structure 
as a parameter, the user must pass a pointer to the structure rather than the 
structure itseif. In this example, the & (address) operator is used when 
passing spname to Cnmpool. 

The user could have defined a pointer variable, assigned the address of the 
structure to that pointer variable and passed the pointer variable to Cnmpool. 
However, this approach introduces the possibility that the user could forget to 
assign the pointer variable before passing it to the hll service routine. 
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Cnmvlc - Convert string to varying length character string 

Cnmvlc enables the user to convert a c string to a varying length character string 
to be used in the NetView hll environment. 

You can choose to provide a simple null-terminated string or a format string as 
input. If formatting is specified, you are responsible for providing a valid argument 
list. Cnmvlc will also convert the input string to hex if desired. This option may be 
helpful when coding command processors that invoke cnmcnmi and cnmkio. 

Cnmvlc calculates the length of the converted string (not including null terminator) 
and stores it in the 2-byte size field of the varying length character string structure. 
The null terminator is actually copied into the buffer portion of the structure even 
though it is not included in the size calculation. This ensures that the buffer portion 
of the structure is null-terminated so that it can be used by other c library routines. 

A pointer to the converted varying length character string structure will be returned 
to the caller on successful completion of this routine. If an error condition occurs, 
Cnmvlc will return a null pointer. Examples illustrating the use of Cnmvlc can be 
found in Chapter 9. 



void *CnmvJc(void *vstring, short convert, char *istring, .„.); 



Where: 

vstring 

A varying length character string to receive the converted string. A varying 
length character string structure consists of a 2-byte size field (short integer) 
followed by a null-terminated buffer (character array). Refer to the "Varying 
Length Character Strings" section of this chapter for further detail. 

convert 

A two byte integer field containing the value or 1, indicating whether or not 
the input string should be converted to hex. Constants nohexcnv and cnvtohex 
have been defined in dsiccons. 

(NOHEXCNV) Do not convert input string to hex. 

1 (CNVTOHEX) Convert input string to hex. 

istrlng 

An input string which follows the conventions specified for the format-string 
parameter of the printf function in c. istring must be null-terminated and may 
or may not contain format specifications (designated by %). The user must 
provide an argument list if formatting is desired. Refer to the printf library 
routine in Common Programming Interface - C Reference for further detail. 

Usage Notes. 

If the user specifies conversion to hex, all of the characters in the input string must 
represent valid hex data. Cnmvlc will return a void pointer if it encounters a char- 
acter which cannot be converted to hex. 

A null pointer will also be returned if the user has specified an invalid value for 
convert or if the format specifications cannot be resolved. 
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Some of the hll services routines (Cnmcnmi and Cnmkio in particular) require the 
user to move hex data into varying length character strings. This can often create 
a problem for the c programmer because of the probability that the null terminator 
(represented as hex zeros) will be interspersed throughout the hex data stream. 
NetView has provided Cnmnvlc (also discussed in this chapter) to alleviate this 
problem. 
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Cnmnvlc - Convert string to varying length character string using length 

Cnmnvlc enables the user to convert a c string to a varying length character string 
to be used in the NetView hll environment. This function is primarily used for 
moving hex data into varying length character strings and is particularly useful 
when coding hll command processors which invoke Cnmcnmi or Cnmkio. 

The function provided by Cnmnvlc is very similar to that of Cnmvlc except that the 
user is required to pass a length field. Cnmnvlc uses the length field to determine 
how many characters to copy from the input string. Also, Cnmnvlc will not accept 
format specifications or an argument list. The user can choose to convert an input 
string to hex if desired. If hex conversion is specified, the length parameter should 
represent the length of the input string before it is converted. 

Once the copy function has completed, Cnmnvlc stores the value of the length 
parameter in the structure. The null terminator is actually copied into the buffer 
portion of the structure even though it is not included in size. 

A pointer to the converted varying length character string structure will be returned 
to the caller on successful completion of this routine. If an error condition occurs, 
Cnmnvlc will return a null pointer. Examples illustrating the use of Cnmnvlc can 
be found in Chapter 9. 



void *Cnmnvlc(void *vstring, short convert, int length, char *istring); 



Where: 

vstring 

A varying length character string to receive the converted string. A varying 
length character string structure consists of a 2-byte size field (short integer) 
followed by a null-terminated buffer (character array). Refer to the "Varying 
Length Character Strings" section of this chapter for further detail. 

convert 

A two byte integer field containing the value or 1, indicating whether or not 
the input string should be converted to hex. Constants nohexcnv and cnvtohex 
have been defined in dsiccons. 

(NOHEXCNV) Do not convert input string to hex. 

1 (CNVTOHEX) Convert input string to hex. 

length 

A four byte integer field specifying the number of bytes to copy from the input 
string. If hex conversion is required, length is the length of the input string 
before it is converted, length must be greater than zero. 

istring 

An input string. If hex conversion is required, all of the characters in the input 
string must represent valid hex data. 

Usage Notes: 

If the user specifies conversion to hex, all of the characters in the input string must 
represent valid hex data. Cnmnvlc will return a void pointer if it encounters a char- 
acter which cannot be converted to hex. 
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A null pointer will also be returned if the user has specified an invalid value for 
convert or length. 

Control Blocks and Include Files 

There are a number of control blocks and include files that are required for exe- 
cution of an hll program (written in c) in the NetView environment, dsic is the main 
file that includes the rest of the files and is necessary to compile hll programs 
written in c. Optional include files have been provided to assist the user in coding 
and maintaining hll programs, dsic, dsiccnm and dsiccons may be tailored to the 
user's needs. 

Note: Tailoring files can lead to better performance in many cases. This is espe- 
cially helpful in performance sensitive environments such as the user exit environ- 
ment. 

The following list of control blocks and include files reside in Appendix C on 
page 279. 

DSIC (Required) Must be included by all hll programs written in c. dsic 

includes all of the external hll control blocks and include files 
needed to compile and run c programs in the NetView environ- 
ment. Refer to the c coding template in Chapter 9 for usage. 

DSICCALL (Required) c definitions for hll service routines. 

DSICCNM (Optional) Defines hll return code constants for c. 

DSICCONS (Optional) Defines constants that are helpful when coding 

High-Level Language programs in c. 

DSICHLB (Required) c mapping of internal control block dsihlb. 

DSICORIG (Required) c mapping of the origin block of the request that 

caused the execution of the program currently running. 

DSICVARC (Required) c mapping of a varying length character string. 

C I/O Considerations 

c provides several input and output routines that allow the user to transmit data 
between main storage and auxiliary storage of a computer, c programs utilizing 
such file i/o capabilities will run in the NetView environment. However, there are 
some important things to consider when doing file i/o in c. 

Each file referenced from your c program correlates to a physical data set in auxil- 
iary storage. The user can specify the file name or a data definition name 
(ddname) when opening a file using fopen. If a ddname is specified, the user must 
ensure that the appropriate data set has been allocated before attempting the 
open. Allocation can be performed under tso or by using the NetView allocate 
command described in NetView Operation. NetView also provides a free 
command to deallocate a data set. 

If the data set is allocated from tso, the user must also add a corresponding data 
definition (dd) statement to the NetView start up procedure. The data definition 
name (ddname) in the dd statement must match the ddname specified in the call to 
the fopen library routine. The dd statement specifies a physical data set name 
(dsname) and gives its characteristics: 

//OUTFILE DD DSN=MYPROG.OUTFILE, ... 
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A dd statement is not necessary if the data set is allocated using the NetView allo- 
cate command. 

The following example illustrates the use of file i/o in an hll program written in c. 
The check for a null pointer has been added to protect against a failure in fopen. 
This check is recommended when opening a file for i/o. 

FILE *0utfd; /* Define file */ 



/•a************************************************ 

/* Check for error opening file for I/O. If fopen error occurred, */ 
/* issue an error message end exit program. */ 

if ((Outfd = fopen("dd:OUTFILE","w")) == NULL) 
{ 

Cnmvlc(&msgbuf,NOHEXCNV, "ERROR OPENING DATA FILE."); 

Cnmsmsg(&msgbuf,MSG,SYSOP,NULLCHAR); 

Hlbptr->Hlbrc = CNM_G00D; 

exit(); 
} 



fprintf (Outfd, ... /* Write to output file */ 

fclose (Outfd); /* Close output file */ 

If the user chooses to write to a common output file from two or more c programs, 
access to the common file must be coordinated by the programs. This can be 
accomplished using NetView's cnmlk service routine if desired. If access is not 
coordinated, the user may experience a system abend 213. 

Special care should be taken when attempting to share open files between two or 
more hll programs. Sharing of open files must be coordinated between the 
sharing programs, pl/i and c cannot share an open file. However, a c program can 
read a file created by pl/i. 

Certain c routines (such as getchar and putchar) are designed to perform functions 
on stdin and stdout. By default, stdin and stdout are directed to the terminal. These 
defaults are not valid and will cause undetermined results if used in the NetView 
environment. Terminal i/o can be done using wait for opinput and cnmsmsg as 
described in Chapter 12. 

Refer to Common Programming Interface C Reference and C/370 User's Guide for 
a more detailed discussion on files and C i/o. 

Considerations for HLL Command Processors 

It is necessary to code a cmdmdl statement in dsicmd for each hll command 
processor that you have written, cmdmdl type will be dependent on the functions 
that your command processor performs. Keep in mind that some of the hll ser- 
vices are only useful when executed under a Data Services Task (dst). There is no 
support for hll command processors running as immediate commands (type=i). 
The cmdmdl statement is described in NetView Administration Reference. 
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C Run-time Considerations 

Most of the run-time errors detected in the c environment are handled by passing a 
return code or a NULL pointer back to the caller. Run-time errors that are detected 
by the operating system generate an interrupt signal which could normally be 
handled by coding a signal function in your program. However, since c programs 
must run with the nostae and nospie options when running in the NetView environ- 
ment, the operating system is unable to generate such interrupts. While debugging 
a c program in the NetView environment, it is allowable to run with the stae and 
spie options until the run-time problems have been resolved. Run-time errors that 
are not detected by the operating system will cause a diagnostic message to be 
written to stderr. See Common Programming Interface C Reference for more detail 
on error handling. 

Return Codes 

Upon completion of an hll service routine, the completion code from that service 
routine is stored in the return code field {Hlbrc) of the hlb control block. This field 
should be checked after each hll service routine invocation. It is recommended 
that this field be utilized when passing return codes between hll programs. 

Note that a return type of void is specified for each of the hll service routines 
defined in dsiccall. This indicates that the hll service routines do not return 
values to the user. The completion code can only be checked by evaluating the 
return code field (Hlbrc) in the hlb. 

For a complete list of hll api return codes, see dsiccnm in Appendix C. Refer to 
Chapter 12 for a list of return codes that apply to each hll service routine. 

In c, normal termination can be achieved by assigning a value to Hlbrc and issuing 
a returnQ statement as shown here. 

Hlbptr->Hlbrc = CNM_G00D; /* Successful completion */ 

return (); /* Return to caller */ 

Restrictions for HLL Programs Written in C 

The following restrictions apply when using c in a NetView environment: 



The following c functions are not supported in the NetView environment: 
C function Recommended HLL alternative 

system Cnmcmd 

The following functions cannot be used without re-directing stdin, stdout, and 
stderr: 



C function 


Recommended HLL alternative 


getchar 


Cnmgetd 


getenv 


Cnminfi, Cnminfc, Origblck, Cnmvars 


gets 


Cnmgetd 


printf 


Cnmsmsg 


putchar 


Cnmsmsg 


puts 


Cnmsmsg 


scant 


Use Cnmgetd to fetch data and sscanf 
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to parse data 

perror Check return code and use Cnmsmsg 

terror to put out message 

Special Considerations: 

1. The c signal function will not work for errors detected by the operating system. 

2. Cnmsmsg cannot be used to display wide character strings. If you need to 
process wide character strings, you will have to redirect stdout and use a c 
function, {print!) 

3. When passing return codes between hll command procedures it is recom- 
mended that you use Hlbrc in the hlb control block (see Appendix C). Using 
exit and return with a return code to pass return codes between hll command 
procedures does not work; however, return and exit can be used to pass 
return codes between your main c program and any procedures it may call. 
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Chapter 9. C High-Level Language Services 

This chapter is an example-oriented discussion of commands and services pro- 
vided by NetView in support of c. The complete syntax and usage of each 
command and service routine can be found in Chapter 12 on page 173. 

C Sample Template 

The following is a coding template sample to be used when coding hll programs in 
c. This template can be used, with your enhancements, to utilize NetView func- 
tions and commands. Further examples in this chapter should be used in conjunc- 
tion with this template. To see a fully functional sample of a NetView c command 
procedure refer to Appendix D on page 295. 
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/* V 

/* (C) COPYRIGHT IBM CORP. 1989 */ 

/* V 

/* IEBCOPY SELECT MEMBER=((CNMS4201,CTMPPLT,R)) */ 

/* */ 

/* (Explanations included in parentheses should be deleted) */ 

/* (after the pertinent information has been filled in. ) */ 

/* V 

/* Descriptive Name: High-Level Language C Template */ 

/* (This is the more descriptive name or title of the module.) */ 

/* V 

/* Function: */ 

/* Template for writing HLL modules in C. */ 

/* (This is the description of what the module does.) */ 

/* (It may be paragraph or pseudocode form. ) */ 

/* . 7 

/* Dependencies: */ 

/* (List conditions that must be met in order for this) */ 

/* (module to perform. An example of this might be a ) */ 

/* (key data area that must already have been built. ) */ 

/* V 

/* Restrictions: */ 

/* (List any limitations this module may have.) */ 

/* V 

/* Language: C */ 

/* V 

/* Input: */ 

/* 1) A pointer to a 4-byte field containing the address of */ 

/* the HLB control block. */ 

/* 2) A varying length character string containing the */ 

/* command or message which invoked this program. */ 

/* If this program was invoked as a command processor, */ 

/* this will be a command string. */ 

/* If this program was invoked as a user exit (other than */ 

/* DSIEX02A), this will be a message string. When driven */ 

/* as DSIEX02A, this string will be empty and the message */ 

/* must be retrieved from the Initial Data Queue (IDATAQ). */ 

/* 3) A 40-byte structure which describes the origin of the */ 

/* request that caused execution of this program. */ 

/* 7 

/* Output: */ 

/* (Describe any output from this module.) */ 

/* 7 

/* Return Codes: returned in Hlbrc */ 

/* For Command Processors: */ 

/* = normal exit */ 

/* -5 = cancelled */ 

/* (List any other return codes meaningful to this module.) */ 

/* For User Exits: */ 

/* = USERASIS (Leave the contents of the message buffer */ 

/* unchanged) */ 

/* 4 = USERDROP (Drop the message buffer) */ 

/* 8 = USERSWAP (Change the contents of the message buffer) */ 

/* 7 
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/* External Module References: */ 

/* (List modules that are called by this module.) */ 

/* */ 

/* Change Activity: */ 

/* date,author: description of changes */ 

/* (A log of the changes made to this module for) */ 

/* (future reference can be kept. ) */ 

/••••••••••A**************************************** 

#pragma runopts (N0EXEC0PS,N0STAE,N0SPIE,ISASIZE(4K),ISAINC(4K)) 

/**************************************************************** 

/* Standard include files 

/************************** ******************************************/ 

#include <stdio.h> /* Standard I/O header */ 

#include <string.h> /* String functions' */ 

#include <stdefs.h> /* Standard definitions */ 

#include <stdlib.h> /* Standard library */ 

#include <stdarg.h> /* Standard args */ 

/* NetView High-Level Language include files */ 

#include "dsic.h" /* Include HLL macros */ 

/•••••it********************************************************** 

/* External data definitions */ 

Dsihlb *Hlbptr; /* Pointer to the HLB */ 

Dsivarch *Cmdbuf; /* Pointer to command buffer */ 

Dsiorig *0rigblck; /* Pointer to Origin block */ 

main(int argc, char *argv??(??)) 

{ 

/••••••••A*************************************** 

/* Internal data definitions */ 

/•A************************************************************* 

/* Convert parameter pointers from character to hex addresses */ 

/************************************************** 

sscanf(argv??(l??),"%x",&Hlbptr); 
sscanf(argv??(2??),"%x",&Cmdbuf); 
sscanf (argv?? (3??) , "%x" ,&0rigbl ck) ; 

/*************************************************************^ 

/* Initialization */ 

/***************************************************************** 

/**********************************************•************ 

/* Execution */ 

/♦•••••A******************************************************* 

Hlbptr->Hlbrc = CNM_G00D; /* Successful completion */ 

} 
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Varying Length Character Strings 

In Chapter 8 the use of varying length character strings with hll command proce- 
dures was discussed. Cnmvlc and Cnmnvlc have been provided for the c user for 
convenience when dealing with varying length character strings. Cnmvlc is espe- 
cially useful when copying NULi-terminated text into a varying length character 
string, and building ru's for the cnmi. Cnmnvlc is especially useful when dealing 
with data that has nulls in it, and data that is not NULL-terminated. 

In several of the samples and examples we have defined our varying length char- 
acter strings as type Dsivarch. This is only for convenience. It is actually more 
efficient to use a varying length character string with a buffer size closer to that of 
your own data. The following examples show how to use Cnmvlc, Cnmnvlc, and 
how to define varying length character strings with different buffer sizes. 



Cnmvlc 



Cnmvlc is used to copy a c character string into a varying length character string. 

The following example copies "Hello World" into a varying length character string 
for use with Cnmsmsg. msg is defined as a varying length character string. 





/* put message in varying length */ 




/* character string... */ 


c(&msg, 


/* ...varying Ten char strng */ 


NOHEXCNV, 


/* ...do not convert to hex */ 


"Hello World"); 


/* ...message */ 




/* display message... */ 


isg(&msg, 


/* ...message text */ 


MSG, 


/* ...type is message */ 


OPER, 


/* ...send message to oper */ 


NULLCHAR) ; 


/* ...not used */ 



Cnmvlc returns a pointer to the varying length character string that data is being 
copied into, and therefore can be imbedded directly into calls to hll service rou- 
tines. The following example shows a call to Cnmvlc imbedded in a call to the 
Cnmsmsg service routine. 

Cnmsmsg (Cnmvlc(&msg, NOHEXCNV, "Hello World"), MSG, OPER, NULLCHAR); 
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The following example copies an ru into a varying length character string and con- 
verts it to hex. ru is defined as a varying length character string and puname is a c 
character string containing the name of the pu that the ru is to be sent to. 

/* put RU in varying length */ 

/* character string... */ 

Cnmvlc(&ru, /* ...varying length char strng */ 

CNVTOHEX, /* ...convert to hex */ 

"81081OGO0O00G00E41038DO0000111OOO006809OO281F108D7E4D5C1D4C5OO"); 

/* ...the RU */ 





/* Send RU over the CNMI... 


*/ 


Cnmcnmi(SENDRPLY, 


/* ...expect a reply 


V 


&ru, 


/* ...RU built above 


V 


puname. buffer, 


/* ...to the PU name specified 


V 


180); 


/* ...timeout after 3 minutes 


V 



The following is an example of using a format string with Cnmvlc. The following 
example copies "Day 1 of five" into a varying length character string, num is 
defined as an integer with a value of 1 and string is defined as a character string 
with a value of "five". 





/* put message in varying length 


V 




/* character string... 


V 


Cnmvlc (&msg, 


/* ...varying Ten char strng 


7 


NOHEXCNV, 


/* ...do not convert to hex 


V 


"Day %d of %s\ 


/* ...format string 


V 


num, 


/*... substitute for %d 


V 


string); 


/* ...substitute for %s 


V 




/* display message... 


V 


Cnmsmsg(&msg, 


/* ...message text 


V 


MSG, 


/* ...type is message 


V 


OPER, 


/* ...send message to oper 


V 


NULLCHAR) ; 


/* ...not used 


V 
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Cnmnvlc 



Cnmnvlc is used to copy c character strings containing null data into varying length 
character strings. 

The following example copies an ru returned by thecNMi into another varying 
length character string, data is defined as a varying length character string. 
getblock is defined as a structure of type origblck, and message is defined as a 
varying length character string. 

Note: The ru in the following example may contain null data. Cnmnvlc copies for 
the length specified regardless of the presence of nulls. 



Cnmgetd(GETLINE, 
&datain, 
1024, 

&getblock, 
CNMIQ, 
1); 



Cnmnvlc (&msg, 

NOHEXCNV, 
data. size, 
data. buffer); 



/* 
/* 
/* 
/* 
/* 
/*. 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



Read in the first RU returned 
...a single RU 
...inti here 

...truncate after 1024 bytes 
...provide a new origin block 
...on the CNMI queue (5) 
...the first RU 
copy varying length character 
string to another varying 
length character string... 
...dest varying len char strng*/ 
...do not convert to hex */ 
...numbers of chars to move */ 
...RU to copy */ 



*/ 

*/ 

*/ 
*/ 

7 
7 
7 
7 
V 
V 



Defining Varying Length Character Strings 

Sometimes it will be necessary to create varying length character strings other 
than Dsivarch. 

The following example copies "Hello World" into a user-defined varying length 
character string. 



typedef struct 

{ 

short size; 

char buffer?? (12??); 

} myvlc; 

main() 

{ 

myvlc msg; 



/* create your own varying length*/ 
/* character string... */ 
/* ...2 byte size field */ 



/* 

/* 



...12 byte buffer 
...data type 



*/ 

7 



/* msg is a varying length */ 
/* character string of type myvlc*/ 



/* copy Hello World into user 
Cnmvlc(&msg,noconvert, "Hello World"); /* defined varying length 

/* character string 
Cnmsmsg(&msg,MS6,0PER,NULLCHAR); /* send message to operator 
} 



V 
V 

7 

7 



Sometimes it is necessary to pass a command buffer larger than 256 characters to 
a c program. In these cases you must change the declaration for Cmdbuf provided 
in the c template. The following example excepts a command buffer larger than 
256 characters and displays it on the mvs operator console. 
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typedef struct 

{ 

short size; 

char buffer?? (300??); 

} myvlc; 

my vie *Cmdbuf; 

main(int argc, char *argv??(??)) 

{ 

sscanf(argv??(2??),"%x",&Cmdbuf); 
Cnmsmsg(Cmdbuf,MSG,SYSOP,NULLCHAR); 
} 



/* create your own varying length*/ 

/* character string... */ 

/* ...2 byte size field */ 

/* ...300 byte buffer */ 

/* ...data type */ 



/* 
/* 
/* 
/* 
/* 
/* 



Cmdbuf is a varying length */ 
character string of type myvlc*/ 
receive paramater list from...*/ 
...Net view */ 

Convert Cmdbuf ptr to hex */ 
display message */ 
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Data Queue Management 



NetView utilizes several data and message queues to work in conjunction with hll 
service routines. Information retrieved from these queues, via the getdata func- 
tion, can be manipulated to enhance your network manageability. The following 
five queues are defined for data and message management. 



TRAPQ 



OPERQ 



DATAQ 



IDATAQ 



CNMIQ 



Queue 1 This queue enables the user to access mes- 

sages placed on it after being trapped as a 
result of an issuance of the trap command for 
messages. 
Queue 2 This queue enables the user to access oper- 

ator input, entered via the go or queue 
command- 
Queue 3 This queue enables the user to access data 
type messages placed on it via the send 
message hll service routine (Cnmsmsg). 
Queue 4 The initial data queue enables the user to 
access the message that invoked the hll 
command by the message automation table or 
the message which drove dsiexo2a. 
Queue 5 This queue enables the user to access cnmi 

solicited data which was solicited via an issu- 
ance of the hll cnmi service routine (cnmcnmi). 



Examples of how the above queues are used with hll command procedures follow. 
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Sending Information 

The following is an example of sending messages. 



/•it*******************************************************************/ 

/* Internal data definitions */ 

/it*********************************************************** 

Dsivarch msgbuf ; /* var len char strng for messages */ 

/•••it********************************************************** 

/* Send a multiline message to user. */ 

Cnmvlc(&msgbuf,0,"LINE 1 OF 3"); 
Cnmsmsg(&msgbuf,MSGj:,OPER,NULLCHAR) 
Cnmvlc(&msgbuf,0, M Line 2 of 3"); 
Cnmsmsg(&msgbuf,MSGJ),OPER,NULLCHAR) 
Cnmvlcf&msgbuf.O/Line 3 of 3"); 
Cnmsmsg(&msgbuf,MSG_F,OPER,NULLCHAR) 

/* Send a multiline message to a task. */ 

Cnmvlc(&msgbuf,0,"Line 1 of 3 M ); 
Cnmsmsg(&msgbuf,MSG - C,TASK,"OPERl 
Cnmvlc(&msgbuf,0,"L7ne 2 of 3"); 
Cnmsmsg(&msgbuf,MSG D.TASK/OPERl 
Cnmvlc(&msgbuf,0,"LINE 3 OF 3"); 
Cnmsmsg(&msgbuf,MSGJ,TASK,"OPERl 

/* Send a message to the system console (only 1-liners). */ 

/••it****************************************************************** / 

Cnmvlc(&msgbuf,0, "HELLO SYSOP"); 
Cnmsmsg(&msgbuf,MSG,SYSOP,NULLCHAR); 



/* Send a message to the authorized receiver. */ 

/•••••••••♦A************************************* 

Cnmvlc(&msgbuf ,0, "HELLO AUTHRCV") ; 
Cnmsmsg(&msgbuf,MSG,AUTHRCV,NULLCHAR); 

/* Send a message to the log. */ 

Cnmvlc(&msgbuf,G,"This should only be in the log"); 
Cnmsmsg(&msgbuf,MSG,NETVLOG,NULLCHAR); 

/••••••A*************************************************** 

/* Send to the sequential log */ 

Cnmvlc(&msgbuf,0,"Test message"); 
Cnmsmsg(&msgbuf,MSG,SEQLOG,"SQLOGTSK"); 

/* Send to a group */ 



Cnmvlc(&msgbuf,0, "Hello group"); 
Cnmsmsg (&msgbuf ,MSG , OPCLASS , "+GR0UP1 " ) ; 
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Synchronous Commands 

The following is a simple example of an hll command processor invoking another 
command. The command could be another hll command, a vtam command, or a 
NetView command. 



••••••A***********************************************************, 



/ 

/* Internal data definitions 

/ 



****************************************************************** 



/ 



Dsivarch command, 
message; 



/* varying len char strng for cmds */ 
/* varying len char strng for msgs */ 



/******************************************************************/ 
/* */ 

/* Execution */ 

/* V 

/••A***************************************************************/ 

/* copy vtam command d net,appls into varying length character */ 
/* string using cnmvlc */ 



Cnmvlc (&command, 

"D NET,APPLS"); 



/* varying length character string */ 

/* do not convert to hex */ 

/* command to copy into varying */ 

/* length character string */ 



/* issue the command 

Cnmcmd(&command); 

if (Hlbptr->Hlbrc != CNM_G00D) 
{ 

Cnmvlc (&message, 
0, 



/* always check re from Cnmcmd 
/* if bad return code from Cnmcmd 
/* place message in varying length 
/* character string... 
/* ...do not convert to hex 



"Command not scheduled successfully"); /* ...message 

/* issue message... 
/* ...message text 
/* ...type is message 
/* ...send to invoking operator 
/* ...not used 



Cnmsmsg(&message, 

MSG, 

OPER, 

NULLCHAR) ; 
} 



7 



*/ 
V 
7 

7 
7 
7 
7 
7 
7 
7 
7 
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Sending Commands 



The following is an example of sending a command to execute on another task. The 
command to be run under the other task could be another hll command, a vtam 
command, or a NetView command. 

This process can be used to execute commands under data services tasks (dst), 
other operator station tasks (ost), or the primary poi task (ppt). 



****************************************************************** , 



/ 

/* Internal data definitions 

/ 



****************************************************************** 



char operl?? (9??) = "0PER1 
Dsivarch logoff, 
msgbuf; 



/ 



'; /* 8 char task name for Cnmsmsg */ 
/* used to store logoff command */ 
/* var Ten char strng for messages */ 



/******************************************************************/ 
/* */ 

/* Execution */ 

/* 7 

/••••♦••A**********************************************************/ 

/* copy command into varying */ 

/* length character string... */ 

Cnmvlc(&logoff, /* ...varying length string */ 

0, /* ...do not convert to hex */ 

"LOGOFF"); /* ...command to be copied */ 



Cnmsmsg (&logoff, 
COMMAND, 
TASK, 
operl); 



/* 

/* 
/* 
/* 
/* 



send the command. .. 
...text of the command to run 
...this is a command 
...run it on a task 
...task name is operl 



7 
7 
7 
7 
7 
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if (Hlbptr->Hlbrc == CNM_GOOD) 
{ 



/* inform user of success 







/* copy message into varying 


V 






/* length character string... 


V 


Cnmvlc(&msgbuf, 




/* ...varying length string 


V 


0, 




/* ...do not convert to hex 


V 


"0PER1 Logoff scheduled successfully"); /* ...message 


V 






/* issue message... 


V 


Cnmsmsg(&msgbuf, 




/* ...text of message 


*/ 


MSG, 




/* ...this is a message 


V 


OPER, 




/* ...to the operator 


V 


NULLCHAR) ; 

} 
else 




/* ...not used 


V 








{ 




/* inform user task not active 


V 


if (Hlbptr->Hlbrc == 
{ 


CNM_TASK_INACTIVE) 






/* copy message into varying 


V 






/* length character string... 


V 


Cnmvlc(&msgbuf, 




/* ...varying length string 


V 


0, 




/* ...do not convert to hex 


V 


"0PER1 Not 


Act 


ive"); /* ...message 


V 






/* issue message... 


V 


Cnmsmsg(8imsgbuf, 




/* ...text of message 


V 


MSG, 




/* ...this is a message 


V 


OPER, 




/* ...to the operator 


*/ 


NULLCHAR); 

} 
else 




/* ...not used 


V 








{ 




/* inform user bad re 


V 






/* copy message into varying 


V 






/* length character string... 


V 


Cnmvlc(&msgbuf, 




/* ...varying length string 


V 


0, 




/* ...do not convert to hex 


V 


"Unexpected 


re 


from Cnmsmsg"); /* ...message 


V 






/* issue the message... 


V 


CnmsmsgC&msgbuf, 




/* ...text of message 


V 


MSG, 




/* ...this is a message 


V 


OPER, 




/* ...to the operator 


V 


NULLCHAR) ; 
} 




/* ...not used 


V 


} 
Hlbptr->Hlbrc = CNM_G00D; 


/* clear re 


*/ 
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Dsiorig origptr; 


/* 


char *token, 


/* 


nodename??(9??); 


/* 


Dsivarch command, 


/* 


msgbuf; 


/* 



Waiting and Trapping 

The following is an example of how to issue a command, trap the output of the 
command, and respond differently depending on the output that is encountered. It 
will activate the given lu, and issue an appropriate message. 

The syntax that it checks for is: 

CACTLU luname 

Where luname is the name of the lu to be activated. 

/* Internal data definitions */ 

/••••••A*************************************** 

work block for Cnmgetd */ 

used to parse command buffer */ 

LU to activate */ 

varying len char strng for cmds */ 

varying len char strng for msgs */ 

/* retrieve node name from command buffer */ 

/************************************************* 

token = strtok((char *) &(Cmdbuf->buffer)," "); /* parse command */ 

token = strtok(NULL," "); /* buffer for LU name */ 
strcpy(nodename, token) ; 

if (strl en (token) > 8) /* node name invalid */ 

token = NULL; 

if nodename specified */ 

copy command into varying length */ 

character string... */ 

...varying length string */ 

...do not convert to hex */ 

"TRAP AND SUPPRESS ONLY MESSAGES 1ST*"); /* ...command */ 

Cnmcmd(&command); /* issue command to trap vtam messages*/ 



if (token != NULL) 


/* 


{ 


/* 




/* 


Cnmvlc(&command, 


/* 


0, 


/* 
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/* build vtam command to activate node */ 

/••••••••••A***************************************************** 



/* copy command into varying length 
/* character string... 
Cnmvlc(&command, /* ...varying length string 
0, /* ...do not convert to hex 

"V NET,ACT,ID=%s",nodename); /* ...command 



V 
V 
V 
*/ 
V 



Cnmcmd(&command) ; 



/* issue command to activate node 



/* put command to wait for 5 sec in 
/* varying length character string... 
Cnmvlc(&command, /* ...varying length string 
0, /* ...do not convert to hex 

"WAIT 10 SECONDS FOR MESSAGES"); /* ...command 



Cnmcmd(&command); 



V 
V 
7 
7 

7 



/* issue command to wait for 5 sees */ 





/* g 


Cnmgetd(GETMSG, 


/* • 


fcmsgbuf, 


/* • 


255, 


/* • 


&origptr, 


/* • 


TRAPQ, 


/* • 


l); 


/* • 



get first trapped message... 
..function is get a message 
..result goes here 
..max input length 
..must provide a work area 
..message is trapped 
..get the first one 



7 
7 
7 
7 
7 
7 
7 



/* 7 

/* Loop through messages until IST093I is found or until no more .*/ 
/* messages are left */ 

/* 7 

/* put wait continue command in */ 
/* varying length character string... */ 



Cnmvlc(&command, 


/* ...varying length string 


V 


0, 


/* ...do not convert to hex 


V 


"WAIT CONTINUE") 


; /* . . . command 


V 


while((strncmp(origptr. 


Orig process, "IST093I", 7) != 0) && 




(Hlbptr->Hlbrc == 

{ 
Cnmcmd(&command); 


CNM_G00D)) 




/* issue wait continue 


*/ 




/* get next trapped message... 


V 


Cnmgetd(GETMSG, 


/* ...function is get a message 


V 


&msgbuf , 


/* ...result goes here 


V 


255, 


/* ...max input length 


V 


&origptr, 


/* ...must provide a work area 


V 


TRAPQ, 


/* ...message is trapped 


V 


l); 


/* ...get the first one 


V 
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if (Mbptr->Hlbrc == CNMJ300D) /* did we find IST093I? */ 

{ /* inform user activation worked */ 

/* build message to inform user activation worked */ 





/* 


copy message into varying length 


7 




/* 


character string... 


7 


Cnmvlc(&msgbuf, 


/* 


...varying length string 


V 


0, 


/* 


...do not convert to hex 


*/ 


"RESOURCE %s 


NOW ACTIVE", nodename); /* ...message 


V 




/* 


issue message... 


V 


Cnmsmsg(&msgbuf, 


/* 


...message to issue 


V 


MSG, 


/* 


...type is message 


7 


OPER, 


/* 


...issue to operator 


7 


NULLCHAR) ; 

} 
else 


/* 


...unused 


7 








{ 


/* 


IST093I not found, must be error 


7 




/* 


copy message into varying length 


7 




/* 


character string... 


7 


Cnmvlc(&msgbuf, 


/* 


...varying length string 


7 


0, 


/* 


...do not convert to hex 


7 


"ERROR - ACTIVATION UNSUCCESSFUL"); /* ...message 


7 




/* 


...message 


7 




/* 


issue message... 


7 


Cnmsmsg(&msgbuf, 


/* 


...message to issue 


7 


MSG, 


/* 


...type is message 


7 


OPER, 


/* 


...issue to operator 


7 


NULLCHAR) ; 
} 


/* 


...unused 


7 


} 
lse 


/* 


nodename not specified 


7 


{ 


/* 


inform user he needs more args 


7 




/* 


copy message into varying length 


7 




/* 


character string... 


7 


Cnmvlc(&msgbuf, 


/* 


...varying length string 


7 


0, 


/* 


...do not convert to hex 


7 


"ERROR - INVALID NODENAME"); /* ...message 


7 




/* 


...message 


7 




/* 


issue the message... 


7 


Cnmsmsg(&msgbuf, 


/* 


...message to issue 


7 


MSG, 


/* 


...type is message 


7 


OPER, 


/* 


...issue to operator 


7 


NULLCHAR) ; 


/* 


...unused 


7 
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Retrieving Information 

The following gives an example of how an hll command processor or user exit 
routine can retrieve information from NetView. Assembler language command 
processors and user exit routines need dsects to access information about 
NetView. hll command processors and user exit routines can access some of this 
information as shown below. Many variables are available. Please refer to the 
command and service routine reference on Cnminfc and Cnminfi for an exhaustive 
list of the values supported ("CNMINFC (CNMINFOC) - Query NetView Character 
Information" on page 209 and "CNMINFI (CNMINFOI) - Query NetView Integer 
Information" on page 211). 



/* Internal data definitions */ 

/A************************************************************** 

Dsivarch cdata, /* store data returned by Cnminfc */ 

msgbuf; /* var len char strng for messages */ 

int idata; /* store data returned by Cnminfi */ 

/* */ 

/* Execution */ 

/* V 
/•••a************************************************* 

/* retrieve date and time... */ 

Cnminfc ("DATETIME", /* ...specify the variable */ 

&cdata, /* ...result goes here */ 

18); /* ...at most eight bytes */ 

cdata. buffer?? (cdata. size??) » '\0'; /* terminate data with null */ 
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/if****************************************************************/ 

/* build message to display results */ 

/••A********************************************* 





/* put message in varying length 


7 




/* character string... 


7 


Cnmvlc(&msgbuf, 


/* varying length string... 


7 


0, 


/* do not convert to hex... 


7 


"DATE/TIME IS: 


%s",cdat a. buffer); /* ...message 


7 




/* display results... 


7 


Cnmsmsg(&msgbuf, 


/* ...text of message 


7 


MSG, 


/* ...is a massage 


7 


OPER, 


/* ...to invoking operator 


7 


NULLCHAR) ; 


/* ...not used 


7 




/* retrieve the number of colors 


7 




/* that the terminal supports... 


7 


Cnminfi( "COLORS ", 


/* ...specify the variable 


7 


&idata) ; 


/* ...result goes here 


7 



/* build message to display results */ 



/* put message in varying length 
/* character string... 
Cnmvlc(&msgbuf, /* ...varying length string 

0, /* ...do not convert to hex 

"NUMBER OF COLORS SUPPORTED ARE: %d\idata); /* ...message*/ 



7 
7 
7 
7 



CnmsmsgC&msgbuf, 


/■ 


MSG, 


f 


OPER, 


f 


NULLCHAR) ; 


f 



/* display results... 
...message text 
...is a message 
...to the invoking operator 
...not used 



7 
7 
7 
7 
7 
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Command List Variable Access 

The following example illustrates the capability to update common global vari- 
ables. This example simply declares, initializes, and alters a variable named 

"GVARIABLE". 

Task globals are updated and read the same way. The only difference is the pool 
name that is specified. 



/•A****************************************************************/ 

/* Internal data definitions */ 

************************************************************** 



/ 

Dsivarch datain, 

variable; 
int length = 24, 
x; 



/ 

store data returned by Cnmvars */ 

store variable name for Cnmvars */ 

max len of data returned by Cnmvars */ 

/* used to increment value returned*/ 

/* ...by cnmvars */ 



/* 

/* 



/••A***************************************************************/ 

V 

V 



/* 
/* 
/* 



Execution 



7 



/A*****************************************************************/ 
/♦••••♦♦♦•••A******************************************************/ 

/* Initialize the variable */ 

/•A****************************************************************/ 





/* 


copy initial value into varying 


*/ 




/* 


length character string... 


V 


Cnmvlc(&datain, 


/* 


...varying length string 


*/ 


0, 


/* 


...do not convert to hex 


V 


"Initial value"); 


/* 


...initial value 


V 




/* 


copy variable name into varying 


V 




/* 


length character string... 


V 


Cnmvlc(Svariable, 


/* 


...varying length string 


V 


0, 


/* 


...do not convert to hex 


V 


"GVARIABLE"); 


/* 


...variable name 


V 




/* 


put an initial value in variabl 


e*/ 


Cnmvars (PUT, 


/* 


...function is write 


V 


&datain, 


/* 


...data is here 


V 


length, 


/* 


...length not used 


*/ 


fcvariable, 


/* 


...variable name 


V 


"CGLOBAL "); 


/* 


...variable pool is cglobal 


*/ 
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****************************************************************** 



/ 

/* Find out the value of the variable */ 

/******************************************************************/ 

7 



Cnmvars(GET, 

&datain, 
length, 
&variable, 
CGLOBAL) ; 



Cnmsmsg(&datain, 
MSG, 
OPER, 
NULLCHAR) ; 



Cnmvlc(&datain, 
0, 
"New value"); 



/* 
/* 
/* 
/* 
/* 
/* 



read the global variable... 
...function is read 
...data goes here 
...truncate after 24 bytes 
...variable name 
...variable pool is cglobal 



/* show operator value... 

/* ...data obtained from varpool 

/* ...type is message 

/* ...send message to operator 

/* ...not used 

/* put new in varying length 
/* character string... 
/* ...do not convert to hex 
/* ...new value 



7 
7 
7 
7 
7 

7 
7 

*/ 

7 
7 

7 
7 
7 
7 



******************************************************************, 



/ 

/* set the global variable 
/ 



****************************************************************** , 





/* u 


Cnmvars(PUT, 


/* • 


&datain, 


/* • 


length, 


/* • 


Svariable, 


/* • 


CGLOBAL) ; 


/* • 



update the global variable... 
...function is write 
...data is here 
...datalen is not used 
...variable name 
...variable pool is CGLOBAL 



7 
7 
7 
7 

7 
7 



/******************************************************************/ 

/* verify variable has been changed */ 



/ 



****************************************************************** 



/ 





/* 


read the global variable ... 


7 


Cnmvars(GET, 


/* 


...function is read 


7 


&datain, 


/* 


...data goes here 


7 


length, 


/* 


...truncate after 24 bytes 


7 


&variable, 


/* 


...variable name 


7 


CGLOBAL) ; 


/* 


...variable pool is CGLOBAL 


7 




/* 


show value to operator ... 


7 


Cnmsmsg(&datain, 


/* 


...data to be displayed 


7 


MSG, 


/* 


...type is message 


7 


OPER, 


/* 


...send message to operator 


7 


NULLCHAR) ; 


/* 


...not used 


7 
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Using Locks 



The previous example illustrated the capability to update common global vari- 
ables, but it did not protect the updating of the variable named "gvariable" by using 
a lock. This example has been modified to obtain a lock before attempting the 
update. 



The lock name can be the same as the global variable, or it can be different. The 
need for protecting the updating needs to be assessed on a case-by-case basis. 

If you decide that it is important to synchronize the updating of a variable, you can 
use the lock method shown below or you may wish to run all the updates on a 
given task. Since only one process can occur on a task at a time, the updates will 
be serialized. Note that this could be any task, including the ppt. 



Dsivarch datain, 


/* 


variable, 


/* 


msg; 


/* 


int length = 24, 


/* 


x; 


/* 




/* 



/•♦••it********************************************************* 

/* Internal data definitions */ 

store data returned by cnmvars */ 
store variable name for Cnmvars */ 
var len char strng for messages */ 
max len of data from Cnmvars */ 
used to increment value returned*/ 
...by Cnmvars */ 

/a*************************************************** 

/* 7 

/* Execution */ 

/* */ 

/* Initialize the variable */ 

/******************************************************************/ 

/* copy initial value into varying */ 

/* length character string... */ 

Cnmvlc(&datain, /* ...varying length string */ 

0, /* ...do not convert to hex */ 

"Initial value"); /* ...initial value */ 



Cnmvlc(&variable, 
0, 
"GVARIABLE"); 



/* copy variable name into varying 
/* length character string... 
/* ...varying length string 
/* ...do not convert to hex 
/* ...variable name 



V 
V 
V 
V 
V 
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/•A****************************************************************/ 

/* Obtain the lock to secure the accuracy of the update */ 

/♦•••A*************************************************************/ 

Cnmlk(LOCK, /* obtain the lock... */ 

&variable, /* ...function is obtain lock */ 

/* ...not used */ 

WAIT); /* ...wait if not available */ 

if (Hlbptr->Hlbrc == CNM_600D) 

Cnmsmsg(Cnmvlc(&msg,0,"got lock"),MSG,OPER,NULLCHAR); 





/* P 


Cnmvars(PUT, 


/* • 


&datain, 


/* • 


length, 


/* • 


&variable, 


/* • 


"CGLOBAL "); 


/* • 



put an initial value in variable*/ 



...function is write 
...data is here 
...length not used 
...variable name 
...variable pool is cglobal 



7 
7 

*/ 

7 
7 



/******************************************************************/ 

/* Find out the value of the variable */ 

/♦A****************************************************************/ 



Cnmvars(GET, 

Sdatain, 
length, 
&variable, 
CGLOBAL) ; 



/* 
/* 
/* 
/* 
/* 
/* 



read the global variable... 
...function is read 
...data goes here 
...truncate after 24 bytes 
...variable name 
...variable pool is cglobal 



7 
7 
7 

*/ 

7 
7 



Cnmsmsg(&datain, 
MSG, 
OPER, 
NULLCHAR) ; 



Cnmvlc(&datain, 
0, 
"New Value"); 



/* show operator value... 

/* ...data obtained from varpool 

/* ...type is message 

/* ...send message to operator 

/* ...not used 



7 
7 
7 
7 
7 



/* put new value in varying length */ 

/* character string... */ 

/* ...do not convert to hex */ 

/* ...new value */ 



****************************************************************** 



/ 

/* set the global variable 

/ 



/ 



****************************************************************** i 



Cnmvars(PUT, 

&datain, 
length, 
&variable, 
CGLOBAL) ; 



/* 


update the global variable... 


7 


/* 


...function is write 


7 


/* 


...data is here 


7 


/* 


...datalen is not used 


7 


/* 


...variable name 


7 


/* 


...variable pool is CGLOBAL 


7 
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/••♦•A*********************************************************** 

/* verify variable has been changed */ 





/* 


read the global variable ... 


V 


Cnmvars(GET, 


/* 


...function is read 


V 


&datain, 


/* 


...data goes here 


V 


length, 


/* 


...truncate after 24 bytes 


*/ 


&variable, 


/* 


...variable name 


*/ 


C6L0BAL) ; 


/* 


...variable pool is CGLOBAL 


7 




/* 


show value to operator ... 


V 


Cnmsmsg(&datain, 


/* 


...data to be displayed 


*/ 


MSG, 


/* 


...type is message 


V 


OPER, 


/* 


...send message to operator 


7 


NULLCHAR) ; 


/* 


...not used 


V 



/••••I******************************************************** 

/* Release the lock to let other tasks update GVARIABLE */ 

Cnmlk (UNLOCK, 

&variable, 
H ii 



/* obtain the lock... 


V 


/* ...function is obtain lock 


7 


/* ...not used 


V 


/* ...not used 


V 



if (Hlbptr->Hlbrc — 0) 

Cnmsmsg(Cnmvlc(&msg,0,"got rid of lock"), MSG, OPER, NULLCHAR); 
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Operator Input 



The following is an example of how to code an HLL command processor to accept 
operator input in single-line mode. The interface is similar to the &pause function 
of the NetView Command List Language. Input is requested by the application 
using the wait for opinput command, input is retrieved by the application using the 
cnmgetd service routine, and the operator can respond using the go command. 

/* Internal data definitions */ 

Dsivarch msgbuf, /* var Ten char strng for messages */ 

command, /* var len char strng for cmds */ 

inbuf; /* store data returned by Cnmgetd */ 

/* V 

/* Execution */ 

/* V 

/* copy message into varying */ 

Cnmvlc(&msgbuf, /* length message string... */ 

0, /* ... do not convert to hex */ 

"Enter operator input data"); /* ... message */ 

/* send a message... */ 

Cnmsmsg(&msgbuf, /* ...text of message */ 

MSG, /* ...single line message */ 

OPER, /* ...to the invoking oper */ 

NULLCHAR); /* ...not used */ 

/* copy command to varying */ 

Cnmvlc(&command, /* length character string...*/ 

0, /* ...do not convert to hex */ 

"WAIT 30 SECONDS FOR OPINPUT"); /* ...command */ 

/* issue command to wait for */ 

Cnmcmd(&command); /* 30 seconds... */ 
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/* get first trapped msg... */ 
if (Hlbptr->Hlbrc = CNMJ)PINPUTJ)N_WAIT) 
{ /* Operator input supplied...*/ 

Cnmgetd(GETMSG, /* ...function is get message*/ 

&inbuf, /* 

255, /* 

Origblck, /* 

2, . /* 

1); /* 



*/ 
V 



..result goes here 
..max input length 
..must provide work area */ 
..msg is on OPINPUT queue*/ 
..get the first one */ 



inbuf.buffer??(inbuf.size??) - 


•\0'; 










/* 


copy op input into varying 


V 


Cnmvlc(&msgbuf, 




/* 


length character string.. 


.*/ 


0, 




/* 


...do not convert to hex 


V 


"OPERATOR INPUT 


IS: %s", 


inbuf. buffer); /* ...message 


V 






/* 


send a message... 


V 


Cnmsmsg(&msgbuf, 




/* 


...text of messgage 


V 


MSG, 




/* 


...single line message 


V 


OPER, 




/* 


...to the invoking oper 


V 


NULLCHAR) ; 

} 
else 




/* 


...not used 


V 










{ 




/* 


No operator input supplied*/ 






/* 


copy message into varying 


V 


Cnmvlc(&msgbuf, 




/* 


length character string.. 


.*/ 


0, 




/* 


...do not convert to hex 


7 


tt N0 OPERATOR INPUT SUPPLIED"); 


/* ... message 


V 






/* 


send a message... 


V 


Cnmsmsg(&msgbuf, 




/* 


...text of messgage 


V 


MSG, 




/* 


...single line message 


V 


OPER, 




/* 


...to the invoking oper 


V 


NULLCHAR) ; 
} 




/* 


...not used 


V 
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VIEW Command Processor 

The following is an example of using the full-screen view command processor. 
First it creates the local variable called parmi, and the variable is initialized. The 
view command processor is invoked, displaying a full-screen panel. For more 
information on view see the NetView Customization Guide. 

The panel that is invoked by the following example appears below: 



+TESTHLL 
if**-*---*-— 



%TEST THE VIEW COMMAND WITH HLL 






Example of using the VIEW command with HLC: 

Notes: The field below, PARMI, is defined as a variable 
by preceding the string PARMI with an ampersand 



$ 

$ 
$ 
% 

$ f by preceding the string PARMI with an ampersand (&). 

$ |. ':;. ■ 

$ 

$ 
$ 
$ 
$ 
$ 
1 
$ 

$ r rNPUT»««=> &PARMI 

%Action===>~&CUR 

$ 
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/* Internal data definitions */ 

/****************************************************************•*/ 

Dsivarch variable, /* store variable name for Cnmvars */ 

data, /* store returned data from Cnmvars*/ 

command; /* varying len char strng for cmds */ 

/* */ 

/* Execution */ 

/* */ 

/* copy variable name into variable */ 

Cnmvlc(&variable, /* length character string... */ 

0, /* ...do not convert to hex */ 

"PARM1"); /* ...variable name */ 

Cnmvars (DCL, /* declare variable to local pool...*/ 

&data, /* ...not used */ 

48, /* ...not used */ 

&variable, /* ...name is parml */ 

LOCAL); /* ...the pool is local */ 

/* copy initialization data to */ 

Cnmvlc(&data, /* variable length character strng..*/ 

0, /* ...do not convert to hex */ 

"the contents of parml go here"); /* ...the data */ 

Cnmvars(PUT, /* initialize parml... */ 

&data, /* ...result goes here */ 

48, /* ...max length is 48 bytes */ 

&variable, /* ...name of variable is parml */ 

LOCAL); /* ...the pool is local */ 

/* Issue the view command. Give the task name as a unique name */ 
/* to go on the View stack. */ 

/* copy command to variable length */ 

Cnmvlc(&command, /* character string... */ 

0, /* ...do not convert to hex */ 

"VIEW %.8s TESTHLL NOMSG INPUT", 0rigblck->0rig_task);/* and*/ 

Cnmcmd(&command); /* issue the command */ 
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Message Processing 



The following example lists the message attributes of a message. The invocation 
must be as a result of an entry in the message automation table, which is docu- 
mented in the NetView Administration Reference. This example will function cor- 
rectly for both single line messages and multiple line messages. 



/••••A*************************************************************/ 
/* Internal data definitions */ 



****************************************************************** 



/* 
/* 
/* 
/* 
/* 
/* 
/* 



orig block for Cnmgetd 
returned data from Cnmgetd 
returned data from Cnmgeta 
var len char strng for messages 
temp var len char strng used... 
...to build messages 
counter 



/ 

7 
V 
V 
V 
*/ 
*/ 
V 



/* array of message attributes... */ 
/* ...to be obtained by Cnmgeta */ 



/ 

Dsiorig getblock; 

Dsivarch inbuf, 
datain, 
message, 
temp; 

int i; 

char *attr??(12??) * { 

"AREAID 

"DESC 

"JOBNAME -, 

"JOBNUM 

"MCSFLAG ", 

"MSGTYP 

"REPLYID ", 

"ROUTCDE", 

"SESSID ' 

"SMSGID ' 

"SYSCONID". 

"SYS ID "}; 



/******************************************************************/ 

/* V 

/* Execution */ 

/* */ 

/******************************************************************/ 



Cnmgetd (GETMSG, 


/* • 


&inbuf, 


/* • 


255, 


/* • 


&getblock, 


/* • 


IDATAQ, 


/* • 


i); 


/* • 



..function is get a message 

..result goes here 

..max input length 

..must provide a work area 

..message on automation queue 

..get the next line 



*/ 

V 

*/ 

V 

*/ 

*/ 
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whil e ( (HI bptr->Hl brc==CNM_GOOD) | j (Hlbptr->Hlbrc=CNM_DATA_TRUNC)) 



{ 


/* 


do while no probs... 


*/ 




/* 


...ignoring truncation 


V 


for(i=0;i<=ll;i++) 


/* 


for 12 possible attributes... 


*/ 


{ 


/* 


get the ith attribute... 


V 


Cnmgeta(attr??(i??), 


/* 


...ith member of the array 


V 


&datain, 


/* 


...result goes here 


*/ 


12, 


/* 


...at most 12 bytes 


*/ 


IDATAQ) ; 


/* 


...on initial data queue 


V 




/* 


put result of above cnmgeta in 


V 


Cnmnvlc(&temp, 


/* 


varying length char string... 


V 


0, 


/* 


...do not convert to hex 


V 


datain.size, 


/* 


...size of result 


V 


datain. buffer); 


/* 


...result to be copied 


V 




/* 


build msg to display results in 


V 


CnmvlcC&message, 


/* 


varying length char string... 


V 


0, 


/* 


...do not convert to hex 


V 


"%s = %s",attr??(i 


??), temp. buffer); /* ...message 


V 




/* 


print that message... 


*/ 


CnmsmsgC&message, 


/*' 


...message text 


V 


MSG, 


/* 


...single line message 


V 


OPER, 


/* 


...to invoking operator 


*/ 


NULLCHAR) ; 


/* 


...not used 


7 



} 

Cnmvlc(&message,0,"LINETYPE = %c",getblock.Orig_line_type); 
CnmsmsgC&message, MSG, OPER, NULLCHAR); 

Cnmvlc(&message,0,"HDRMTYPE = %c",getblock.Orig_msg_type); 
Cnmsmsg(&message, MSG, OPER, NULLCHAR); 

Cnmvlc(&message,0,"MSGID = %.8s",getblock.0rig_process); 

/* orig fields not NULL..*/ 
/* ...terminated */ 

CnmsmsgC&message, MSG, OPER, NULLCHAR); 

inbuf.buffer??(inbuf.size??) - '\0'; /* append NULL to end of */ 

/* ...data retrieved by Cnmgetd */ 

Cnmvlc(&message,0,"MSGSTR = %s",inbuf. buffer); 
CnmsmsgC&message, MSG, OPER, NULLCHAR); 





/* 


Cnmgetd(GETLINE, 


/* 


&inbuf, 


/* 


255, 


/* 


&getblock, 


/* 


IDATAQ, 


/* 


l); 


/* 



} 

Hlbptr->Hlbrc == CNM_G00D; 



get first trapped message... 
...function is get a message 
...result goes here 
...max input length 
...must provide a work area 
...message is from automation 
...get the next line 



*/ 
V 
V 
V 
V 
V 
V 
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Scope Checking 



The following is an example of the scope checking capabilities provided by 
NetView. In this example, the user is required to set up the following elements for 
the command (shown below): 

1. operator id 

2. operator classes that can access the command 

3. operator profile 

The command gives the return code that the scope check service routine returned 
to the operator. 

The syntax that this command checks for is: 
CSCOPCK PARMx(VALx) 

The following is the setup for the scope check example. 

In DSIPARM(DSICMD): 

• Define the operator classes that can access the command, its keywords, and 
its keyword values. 

• The example below says that the command cscopck can be executed by opera- 
tors in scope class 1 and 2. Scope class 1 can issue any keyword or keyword 
value, but scope class 2 cannot use the value of vali with keyword parm2, and 
scope class 2 cannot issue parm3 at all. 



CSCOPCK 


CMDMDL 


M0D=CSC0PCK, RES=N , TYPE=RD 




CMDCLASS 


1,2 


PARM2 


KEYCLASS 


1,2 


VALI 


VALCLASS 


1 


PARM3 


KEYCLASS 


1 


VALI 


VALCLASS 


1 



In DSIPARM(DSIOPF): 

• Define the operator ids and the profiles that the operator ids can use. 

JOE OPERATOR PASSWORD=USER 

PROFILEN DSIPR0F3 

In DSIPRF(profilename): 

• Define the operator class value that will correspond to the profile that the oper- 
ator logs on with. 

DSIPR0F3 PROFILE 
OPCLASS 3 
END 
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/* Internal data definitions */ 



Dsivarch datain, 
variable, 
msg; 

int length = 24, 
x; 



/* 
/* 
/* 
/* 
/* 
/* 



store data returned by cnmvars */ 
store variable name for Cnmvars */ 
var len char strng for messages */ 
max len of data from Cnmvars */ 
used to increment value returned*/ 
...by Cnmvars */ 



/****************************************•*************** 

/* V 

/* Execution */ 

/* V 

/* Initialize the variable */ 
/****************************************•***************** 

/* copy initial value into varying */ 

/* length character string... */ 

Cnmvlc(&datain, /* ...varying length string */ 

0, /* ...do not convert to hex */ 

"Initial value"); /* ...initial value */ 



copy variable name into varying */ 
length character string... */ 
...varying length string */ 
...do not convert to hex */ 
...variable name */ 



/* Obtain the lock to secure the accuracy of the update */ 

Cnmlk(L0CK, /* obtain the lock... */ 

Invariable, /* ...function is obtain lock */ 

/* ...not used */ 

WAIT); /* ...wait if not available */ 

if (Hlbptr->Hlbrc « CNM_G00D) 

Cnmsmsg(Cnmvlc(&msg,0,"got lock"), MSG, 0PER,NULLCHAR); 





/ 


Cnmvlc(&variable, 


/ 


0, 


/ 


"GVARIABLE"); 


/ 





/* P 


Cnmvars (PUT, 


/* • 


&datain, 


/* • 


length, 


/* • 


&variable, 


/* • 


"CGLOBAL "); 


/* • 



put an initial value in variable*/ 

...function is write 

...data is here 

...length not used 

...variable name 

...variable pool is cglobal 



*/ 

V 
V 
V 
V 
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/•••♦•••A**********************************************************/ 

/* Find out the value of the variable */ 

/•••••••A**********************************************************/ 



Cnmvars(GET, 

&datain, 
length, 
&variable, 
CGLOBAL) ; 



Cnmsmsg(&datain, 
MSG, 
OPER, 
NULLCHAR) ; 



Cnmvlc(&datain, 
0, 
"New Value"); 



/* 
/* 
/* 
/* 
/* 
/* 



read the global variable... 
...function is read 
...data goes here 
...truncate after 24 bytes 
...variable name 
...variable pool is cglobal 



/* show operator value... 

/* ...data obtained from varpool 

/* ...type is message 

/* ...send message to operator 

/* ...not used 



7 
7 
7 
7 
7 
7 

7 
7 
7 
7 
7 



/* put new value in varying length */ 
/* character string... .*/ 
/* ...do not convert to hex */ 
/* ...new value */ 



A******************************************************************/ 
/* set the global variable */ 



/ 



****************************************************************** 





/* u 


Cnmvars(PUT, 


/* • 


&datain, 


/* • 


length, 


/* • 


Invariable, 


/* • 


CGLOBAL) ; 


/* • 



update the global variable... 
...function is write 
...data is here 
...datalen is not used 
...variable name 
...variable pool is CGLOBAL 



/ 



7 
7 
7 
7 
7 

7 



/A*****************************************************************/ 

/* verify variable has been changed */ 



/ 



****************************************************************** 



/ 





/* 


read the global variable ... 


7 


Cnmvars(GET, 


/* 


...function is read 


7 


&datain, 


/* 


...data goes here 


7 


length, 


/* 


...truncate after 24 bytes 


7 


&variable, 


/* 


...variable name 


7 


CGLOBAL) ; 


/* 


...variable pool is CGLOBAL 


7 




/* 


show value to operator ... 


7 


Cnmsmsg(&datain, 


/* 


...data to be displayed 


7 


MSG, 


/* 


...type is message 


7 


OPER, 


/* 


...send message to operator 


7 


NULLCHAR) ; 


/* 


...not used 


7 



/******************************************************************/ 

/* Release the lock to let other tasks update GVARIABLE */ 
****************************************************************** 



/ 

Cnmlk (UNLOCK, 
&variable, 



'); 



/* obtain the lock... 

/* ...function is obtain lock 

/* ...not used 

/* ...not used 



/ 

7 
7 
7 
7 



if (Hlbptr->Hlbrc == 0) 

Cnmsmsg(Cnmvlc(&msg,0,"got rid of lock"), MSG, OPER, NULLCHAR); 
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Altering Data 



This DSIEX02A exit routine changes the echoed command message (msgtype=*) to 
be more informative by giving the time as weil as the fact that the command was 
entered. 

Example output with input of WHO: 



Without exit: 
WHO 

With exit: 
Command entered was: "WHO" at 12:00:00 



/********************************************************************/ 

/* V 

/* Descriptive Name: High Level Language C Dsiex02a Example */ 



Change Activity: 

date, author: description of changes 



V 
*/ 



f* 

r 

/••••••••A***********************************************************/ 

#pragma runopts (N0EXEC0PS,N0STAE,N0SPIE,ISASIZE(4K) ,ISAINC(4K)) 

/********************************************************************/ 

/* Standard include files 

/•••••♦••A***********************************************************/ 

#include <stdlib.h> 
#include <stdarg.h> 



/* Standard library 
/* Standard args 



V 

V 



/♦•••••••A***********************************************************/ 

/* NetView high level language include files */ 

/********************************************************************/ 

#include "dsic.h" /* Include HLL macros */ 



/ 



******************************************************************** 



/ 



/* External data definitions */ 

/********************************************************************/ 

Dsihlb *Hlbptr; /* Pointer to the HLB */ 

Dsivarch *Cmdbuf; /* Pointer to command buffer */ 

Dsiorig *0rigblck; /* Pointer to Origin block */ 
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main(int argc, char *argv??(??)) 
{ 



******************************************************************, 



/ 

/* Internal data definitions 



******************************************************************, 



/ 

Dsiorig getblock; 

Dsivarch datain; 

Dsivarch time; 

Dsivarch msgbuf; 



/* Area for the Origin Block 
/* Old command text 
/* Area for time 
/* message buffer 



V 
V 
7 
7 



/ 



****************************************************************** 



/ 



/* Convert parameter pointers from character to hex addresses */ 

/******************************************************************/ 

sscanf (argv?? (1??) , "%x" ,&H1 bptr) ; 
sscanf (argv?? (2??) , "%x" ,&Cmdbuf ) ; 
sscanf (argv?? (3??) , "%x" ,&0rigblck) ; 

/******************************************************************/ 

/* Initialization */ 

/******************************************************************/ 

/******************************************************************/ 
/* */ 

/* Execution */ 

/* 7 

/•••••••••••A******************************************************/ 

/* Retrieve the time... 

', /* ...variable is time of day 

/* ...the result goes here 

/* ...max length of 255 



Cnminfc ("TIME 
&time, 
255); 



7 
7 
7 
7 



Cnmgetd(PEEKLINE, 
&datain, 
255, 

&getblock, 
IDATAQ, 

l); 



/* 
/* 
/* 
/* 
/* 
/* 
/* 



Peek the msg before altering 
...subfunction is peek 
...result goes here 
...max length is 255 
...use new Origin block 
...initial data queue (4) 
...check the first line 



V 

V 
V 
V 
V 
V 
V 



datain. buffer?? (datain. size??) = '\0'; /* put null at end of data*/ 

/* Echo'ed message? */ 

if (getblock. Orig_msg_type == '*') { 

Cnmvlc(&msgbuf,0, "Command entered was: %s at %. 8s", datain. buffer, 
time. buffer); 

/* 
/* 
/* 
/* 
/* 
/* 



Cnmaltd(REPLINE, 
Smsgbuf, 
&getblock, 
IDATAQ, 

i); 



Replace the text... 
...subfunction is replace 
...text of new message 
...used peeked Origin block 
...initial data queue 
...replace the first line 



V 
V 
V 
V 
V 
V 



} 

Hlbptr->Hlbrc = CNM_G00D; 
} 



/* clear re 



7 
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Storage Access 



The following example illustrates how to display the character representation of 
the contents of the storage that NetView can access. For example, after locating 
the address of the main vector table using dispmod dsimntex, you can display the 
first four bytes of the dsimvt control block, which for NetView R3 this will contain 
the character string NV13. 



/ 



**************************************************************** 



/ 



/* Internal data definitions */ 

/•••••♦•A**********************************************************/ 



int numparms; 


/* 


int *xaddr; 


/* 


int numbytes; 


/* 


char *inbufr p; 




char inputbfr??(4097??) = " «'; 


/* 


char *srceptr; 


/* 


int i,x; 


/* 


Dsivarch msgbuf; 


/* 



Number of parms scanned 
Hex value of srcejptr 
Number of bytes to display 

Buffer where data is copied 
Address to copy from 
Work counter 
Buffer for Cnmsmsg 



V 
V 

*/ 

V 
V 

V 
V 



/ 



****************************************************************** 



/ 



V 
V 



/* 

/* Execution 

/* V 

/••♦••••A**********************************************************/ 

inbufrj? = inputbfr; 

numbytes = 0; 

numparms = sscanf((char *) &(Cmdbuf->buffer), /* parse cmd buffer */ 

"%*s%x%x", /* Format string */ 

&xaddr, /* The address to display */ 

&numbytes); /* For this number of bytes */ 

if (numparms != 2) /* Address and length given ? */ 

{ 
Cnmvlc(&msgbuf,0, "Invalid number of parameters"); 

Cnmsmsg (&msgbuf, /* No, display error message... 

MSG, /* ...message 

OPER, /* ...to the operator 

NULLCHAR); /* ...not used 

Hlbptr->Hlbrc =1; /* set return code 

return; /* Terminate processing 
} 



V 
V 
V 
V 

V 
V 
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/* A valid length given? 



/ 



if (numbytes <= G) 

{ 
Cnmvlc(&msgbuf,0," Invalid length given"); 
Cnmsmsg(&msgbuf, /* No, display error message... */ 



} 



MSG, 

OPER, 

NULLCHAR) ; 
Hlbptr->Hlbrc = 1; 
return; 



/* ...message 

/* ...to the operator 

/* ...not used 

/* set return code 

/* Terminate processing 



/* A valid length given? 



7 
7 
7 
7 
7 



if (numbytes >= 4096) 

{ 
Cnmvlc(&msgbuf,0, "Invalid length given, must be less than FFF"); 



/ 



} 



Cnmsmsg(&msgbuf, 

MSG, 

OPER, 

NULLCHAR) ; 
Hlbptr->Hlbrc = 1; 
return; 



/* No, display error message... */ 

/* ...message 

/* ...to the operator 

/* ...not used 

/* set return code 

/* Terminate processing 



7 
7 
7 
7 
7 



if (xaddr != NULL) 

{ 
Cnmcpys(&xaddr, 

&inbufr_p, 

numbytes, 

FIXTOFIX); 



/* If valid address then... 

/* Copy storage... 

/* ...from the address given 

/* ...to the internal buffer 

/* ...for up to FFF bytes 

/* ...data is fixed length type 



if (Hlbptr->Hlbrc == CNM_G00D) /* Good re? 

{ 
for 0=1; i <= (x=ceil(numbytes/64.0)*64); i = i + 64) 

{ 

if (((numbytes - i) +1) >= 64) 

{ 

memmove(msgbuf. buffer, inputbfr+(i-l), 64); 

msgbuf.size = 64; 

} 
else 

{ 

memmove(msgbuf. buffer, inputbfr+(i-l), numbytes % 64); 

msgbuf.size = numbytes % 64; 

} 



Cnmsmsg(&msgbuf, 


/* Display 64 bytes of storage. 


..*/ 


MSG, 


/* ...message 


7 


OPER, 


/* ...to the operator 


7 


NULLCHAR) ; 
} 


/* ...not used 


7 


} 
else 

{ 

Cnmvlc(&msgbuf,0,"lnval 


/* Else bad return code 


7 


lid or protected address"); 




Cnmsmsg(&msgbuf, 


/* Send error message... 


7 


MSG, 


/* . . .message 


7 


OPER, 


/* ...to the operator 


7 


NULLCHAR) ; 


/* ...not used 


7 
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Data Set Access 



The following is an example of opening (using cnmmemo), reading (using cnmmemr) 
and closing (using cnmmemc) NetView partitioned data sets. This example reads a 
member of dsiparm called dsidmn, and displays it to the operator. 

/* Internal data definitions */ 

/******************************************************************/ 

int token; /* Token used to match open to */ 

/* ...read and close */ 

Dsivarch msgbuf; /* Line that is read */ 



/* Open the member */ 

/* Open the data set member. . . */ 

Cnmmemo (&token, /* ...token returned by Cnmmemo */ 

"DSIPARM ", /* ...ddname of PDS */ 

"DSIDMN "); /* ...member name of PDS */ 

if (Hlbptr->Hlbrc != CNM_G00D) 

{ 

Cnmvlc(&msgbuf, /* Put error message in msgbuf... */ 

0, /* ...do not convert to hex */ 

"OPEN FOR DATASET FAILED RC= %d\Hlbptr->Hlbrc); /* msg */ 

/* Send message... */ 

/* ...member in DDNAME not found */ 

/* ...single line message */ 

/* ...to the operator */ 

/* ...taskname ignored */ 



Cnmsmsg(&msgbuf, 
MSG, 
OPER, 
NULLCHAR) ; 



} 
else 
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/******************************************************************, 



Read the member 



/A***************************************************************** , 



Cnmmemr( token, 
Smsgbuf, 
80); 



/* Read the first record... 
/* ...provide token from OPEN 
/* ...result goes here 
/* ...read 80 bytes 



while (Hlbptr->Hlbrc == CNM_G00D) /* Read until EOF 



{ 



} 



msgbuf.size = 72; 

Cnmsmsg(&msgbuf, 
MSG, 
OPER, 
NULLCHAR) ; 

Cnmmemr( token, 
Smsgbuf, 
80); 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



only write 72 bytes of record 
Write out last record read... 
...write first 72 bytes 
...single line message 
...to the operator 
...taskname ignored 
Read the next record... 
...provide token from OPEN 
...result goes here 
...read 80 bytes 



V 

V 
V 
V 



V 
7 
V 
V 
V 
V 
V 
V 
V 
V 



/•it*********************************************************** 

/* Close the member */ 



} 



Cnmmemc( token); 



/* Close the PDS member... 
/* ...provide token from OPEN 



V 

V 
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CNMI 



NetView provides the Cnmcnmi service routine for use in communicating with 
devices in the network via the Communications Network Management Interface 
(Cnmi). Any data that is returned may be accessed using the Cnmgetd service 
routine to retrieve records from the Cnmi solicited data queue (cnmiq). 

The following example uses the Cnmcnmi service routine to send a request- 
product-set-id data request to a specified pu. Any data returned is sent as a 
message to the operator. 



The syntax of the command is: 

CCNMI puname <OWN|ALL> 

where: 

puname is the name of the PU to be retrieved (required) 

OWN implies that vital product data is to be 
retrieved for the PU only (default) 

ALL implies that vital product data is to be 

retrieved for the PU and its attached ports 

/* External data definitions */ 

/****************************************************************** 

typedef struct 

{ 

short size; 

char buffer?? (1025??); 

} Bigvlc; 
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main(int argc, char *argv??(??)) 
{ 



/******************************************************************/ 

/* Internal data definitions */ 

/******************************************************************/ 

/* 
/* 
/* 
/* 
/* 



int rcode; 
int count; 
Dsivarch puname; 
Dsivarch msgbuf; 
Dsiorig getblock; 
Bigvlc datain; 
char ownorall??(4??); 
Dsivarch fwdru; 
Dsivarch ru; 
Dsivarch own; 
Dsivarch all; 
Dsivarch puhdr; 
Dsivarch endofru; 
char *ptr; 



Return code 

Count of scanned args 

puname varying length 

Message buffer 

Area for the work orig block 
/* Buffer for the RU 
/* Own or all placeholder 
/* Forward RU 
/* RU data 

81 if own specified 

83 if all specified 

puname header 

end of RU 

ptr used to build fwdru 



/* 
/* 
/* 
/* 
/* 



V 

*/ 

*/ 

V 

*/ 

V 

7 

*/ 

V 
7 

7 

7 
7 
7 



{********************************************************************. 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



Vital Product Data RU definitions 



From the VTAM Progamming Manual, a forward RU is defined below 



Byte 

1 
2 
3 
4 



Value Description 

81 Network services, logical services 
08 Management services 
10 Request code 
00 Format 
00 Ignore target names, 
Solicit a reply, and 
No CNM header contained 
00 Reserved 
7 000E Length of NS RU 

15 NS RU -- NMVT — documented in SNA Ref Sum 
A 41038D NS Header for NMVT 
C 0000 Retired 
E 0111 PRID 

00 unsolicited NMVT, 

only NMVT for this PRID 
One MS major vector 

Length field of PSID (Product Set ID) vector 
Code point for PSID 
Length of subvector 
02 Length of subvector 
81 Request information on control unit only 
83 Request information on control unit and its 
attached devices 

16 Fl From VTAM programming, PU 

17 08 Length of PU name 

18 PUNAME Eight byte PUNAME, left justified 
20 00 End of RU 



5 

6- 

8- 

8- 

B- 

D- 

F 

10- 

10- 

12- 

14 

14 

15 

15 



16 

11 0006 
13 8090 
-15 



V 
V 
V 
V 
V 
*/ 

V 
V 
V 
V 
V 
V 
V 
V 
V 
V 

*/ 
*/ 
*/ 

V 

*/ 

V 
V 

*/ 
*/ 
*/ 
*/ 
*/ 
*/ 

V 

*/ 
*/ 

V 



f ******************************************************************** i 
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/* Initialization */ 

/••vie***************************************************** 

Cnmvl c (&ru , 1 , "81O81GOOOGG0O00E41O38DOO0O01 1 1000006809002 " ) ; 

Cnmvl c (Sown, 1, "81"); 

Cnmvl c(&al 1,1, "83"); 

Cnmvl c(&puhdr,l,"F108"); 

Cnmvl c(&endofru,l, "00"); 

rcode = 0; 

/* V 

/* Execution */ 

/* V 

/A**************************************************************** 

ptr = (char *) fcfwdru. buffer; 

count « sscanf((char *) &(Cmdbuf->buffer),"%*s%s%s", 
puname. buffer,ownoral 1 ) ; 

puname.size = strl en (puname. buffer); 

if (puname.size < 8) /* Pad with blanks if needed */ 

strncat (puname. buffer," ",8 - puname.size); 

if ((count ==1) !! (strncmp(ownoran,"0WN",3) = 0)) 
{ 

memmove (ptr, ru.buffer.ru. size) ; 
ptr=ptr+ru.size; 

memmove(ptr, own. buffer, own. size); 
ptr=ptr+own.size; 

memmove(ptr,puhdr.buffer,puhdr.size); 
ptr=ptr+puhdr.size; 

memmove (ptr, puname. buffer, puname. size); 
ptr=ptr+puname.size; 

memmove(ptr,endofru.buffer,endofru.size); 
fwdru.size = ru.size+own.size+puhdr.size+puname.size+endofru.size; 

} 

else 
if (strncmp(ownoran, ,, ALL",3) == 0) /* ALL specified */ 

{ 

memmove(ptr, ru. buffer, ru. size); 

ptr=ptr+ru.size; 

memmove(ptr, all .buffer, all .size) ; 

ptr=ptr+all.size; 

memmove(ptr,puhdr.buffer,puhdr.size); 

ptr=ptr+puhdr.size; 

memmove(ptr, puname. buffer, puname. size); 

ptr=ptr+puname.size; 

memmove(ptr,endofru.buffer,endofru.size); 

fwdru.size = ru.size+all.size+puhdr.size+puname.size+endofru.size; 

} 
else /* Else invalid parm inform user */ 

{ 

Cnmvl c(&msgbuf,0," Invalid command syntax"); 

Cnmsmsg(&msgbuf,MSG,TASK,Origblck->Orig_task); 

rcode « 8; 

} 
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if (rcode == 0) { 

Cnmcnmi(SENDRPLY, 
&fwdru, 

puname. buffer, 
18G); 



/* 
/* 
/* 
/* 
/* 
/* 



Good so far? 

Send RU over the CNMI... 

...expect a reply 

...RU built above 

...to the PU name specified 

...timeout after 3 minutes 



if (Hlbptr->Mbrc == CNM_G00D) /* Everything ok? 



{ 



Cnmgetd(GETLINE, 
fcdatain, 
1624, 

&getblock, 
CNMIQ, 
1); 

while (Hlbptr->Hlbrc == G) 
{ 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



Yes, continue 

Read in the first RU returned 

...a single RU 

...inti here 

...truncate after 1Q24 bytes 

...provide a new origin block 

...on the CNMI queue (5) 

...the first RU 

/* End of queue reached? 



Cnmsmsg(&datain, 
MSG, 
TASK, 



/* 
/* 
/* 
/* 



Send info to the operator... 
...from here 
...issue message 
...to the task 
Origblck->Orig_task); /* ...that originated request 
/* Read in the next RU returned 



Cnmgetd(GETLINE, 
&datain, 
1024, 

&getblock, 
CNMIQ, 
1); 



/* 
/* 
/* 
/* 
/* 
/* 



..a single RU 

..inti here 

..truncate after 1Q24 bytes 

..provide a new origin block 

..on the CNMI queue (5) 

..the first RU 



7 
7 
7 

7 
7 
7 



7 
7 
7 

7 

7 
7 
7 
7 

7 

7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 



else 



/* CNMI error 
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{ 

/* Not invoked under a DST */ 
if (Hlbptr->Hlbrc == CNMJADJNVOCATION) 

Cnmvlc(&msgbuf, /* Buffer for message text */ 

0, /* Do not convert to hex */ 

"Must run under a DST"); /* Error message */ 
else 

/* PU never answered request */ 
if (Hlbptr->Hlbrc == CNM_TIME_OUT) 

Cnmvlc(&msgbuf, /* Buffer for message text */ 

0, /* Do not convert to hex */ 

"PU never answered"); /* Error message */ 
else 

/* PU gave a negative response */ 
if (Hlbptr->Hlbrc == CNM_NEG_RESPONSE) 

Cnmvlc(&msgbuf, /* Buffer for message text */ 

0, /* Do not convert to hex */ 
"PU gave negative response"); 
else 

/* Cnmi failure */ 

Cnmvlc(&msgbuf, /* Buffer for message text */ 

0, /* Do not convert to hex */ 

"CNMI request failed re = %d\ 

Hlbptr->Hlbrc); /* Re from CNMI routine */ 

CnmsmsgC&msgbuf, /* Send error message to user... */ 

MSG, /* ...single line message */ 

TASK, /* ...dest. type task */ 
Origblck->0rig_task); /* ...dest. id origin task */ 

} /* End of CNMI error */ 

} /* End of Good so far */ 

Hlbptr->Hlbrc = rcode; /* Issue re */ 
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VSAM (Keyed File Access) 

The following is an example of coding a Netview hll command processor that 
allows i/o to a vsam file via the Cnmkio service routine. 

It must execute on a dst. To run this command on a dst, either use the Cnmsmsg 
service routine (with a type of command) or use the excmd command. 

This example will create a data base that contains 5 records with the following 
keys and data: 



KEY 


DATA 


01 


A 


02 


B 


03 


C 


04 


D 


05 


E 
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A******************************************************************/ 

/* Internal data definitions */ 

/••A***************************************************************/ 



Dsivarch rec; 
Dsivarch inrec; 
Dsivarch key; 
Dsivarch msg; 
char outdata??(6??) = 
char keydata??(ll??) 
char *keyptr; 
char *outptr; 
int i; 



store output data for Cnmkio */ 

store data returned by Cnmkio */ 

store key for Cnmkio */ 

store messages to be displayed*/ 

"ABCDE"; /* output data 

= "0102030405"; /* data for building keys 

/* pointer to key data 

/* pointer to output data 

/* counter 



/* 
/* 
/* 
/* 
/* 



*/ 

*/ 

V 

*/ 
V 



A******************************************************************/ 

/* V 

/* Execution */ 

/* V 

A******************************************************************/ 



***************************************************************** 



/ 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



WRITE OUT 5 RECORDS... 

PUT DIRECT must be used for new records, and PUT UPDATE 
must be used for old records. Therefore, we will use GET 
EQual to determine if the record is new or not. If new, 
then a PUT DIRECT will follow... if not, then a put update 
follows. 



/ 
*/ 

V 

V 

*/ 

V 
V 
V 



/* For 5 records 



/* */ 

/******************************************************************/ 

keyptr = keydata; 
outptr = outdata; 
for (i =0; i <= 4; 1++) 

{ 

memmove(key. buffer, keyptr, 2); /* Set key portion of record 
key. size = 2; /* Set size of key buffer 

keyptr = keyptr+2; /* Get next key in table 

memmove(rec. buffer, key. buffer, 2); /* Record must have key 1st 
memmove(rec. buffer+2, outptr, 1);/* attach data to key 
rec. size = 3; /* Set size of record 

outptr « outptr+1; /* Set pointer to record 



Cnmkio (GET_EQ, 
&inrec, 
10, 
&key, 
UPDATE) ; 



/* 
/* 
/* 
/* 
/* 
/* 



Call KEYIO... 
...requesting a get 
...data goes in here 
...10 bytes max input 
...key is in key 
...this is an update 



*/ 
*/ 

V 
V 

*/ 

7 
*/ 

*/ 
V 
V 
*/ 
V 
V 
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if (Hlbptr->Hlbrc == CNMJOT_FOUND) 





/* 


Call KEYIO... 


*/ 


Cnmkio(PUT, 


/* 


...requesting a put 


7 


&rec, 


/* 


...data goes in here 


*/ 


0, 


/* 


...not used 


7 


&key, 


/* 


...key is in key 


7 


DIRECT); 


/* 


...this is an update 


7 


else 










/* 


Call KEYIO... 


7 


Cnmkio(PUT, 


/* 


...requesting a put 


7 


&rec, 


/* 


...data goes in here 


7 


0, 


/* 


...not used 


7 


&key, 


/* 


...key is in key 


7 


UPDATE) ; 


/* 


...this is an update 


7 



if (Hlbptr->Hlbrc != CNM GOOD) 
{ /* if put failed */ 

I* put message in varying length */ 
Cnmvlc(&msg, /* character string... */ 

0, /* do not convert to hex */ 

"Cnmkeyio PUT request failed with RC: %d",Hlbptr->Mbrc); 



} 



Cnmsmsg(&msg, 

MSG, 

OPER, 

NULLCHAR) ; 
} 



/* put out error message... 

/* ...message text 

/* ...type is message 

/* ...send to issuing operator 

/* ...not used 



7 
7 
7 
7 
7 



/••♦•••A************************************************** 

/* Read in the 5 records... */ 

/A*************************************************************** 

keyptr = keydata; 

for (i = 0; i <= 4; i++) /* For 5 records 

{ 

memmove(key. buffer, keyptr, 2); /* Set key portion of record 
key. size » 2; 
keyptr = keyptr+2; 

/* Call KEYIO... 
Cnmkio(GET_EQ, /* ...requesting a put 



7 
7 



&inrec, 
10, 
&key, 
NOUPDATE) ; 



/* 
/* 
/* 
/* 



..data goes in here 
..not used 
..key is in key 
..this is an not update 



7 
7 
7 
7 
7 
7 



} 



inrec.buffer??(inrec.size??) = '\0'; /* add NULL to end of */ 

/* ...data 7 
Cnmvlc(&msg,0,"Key: %.2s Record: %s", key. buffer, inrec. buffer); 
Cnmsmsg(&msg, MSG, SYSOP, NULLCHAR);/* display key and record */ 



Hlbptr->Hlbrc = CNM_G00D; 



/* Issue clean re 



7 
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DST User Exit 



The following is an example of coding a Netview hll user exit routine that primes 
an empty vsam data base for a dst. If a vsam data base has not been primed (has 
at least one record), subsequent i/o requests will fail. 



/* V 

/* Descriptive Name: High Level Language C DSIEX02A Example */ 



/* Change Activity: */ 

/* date, author: description of changes */ 

/********************************************************************/ 

#pragma runopts (N0EXEC0PS,N0STAE,N0SPIE,ISASIZE(4K),ISAINC(4K)) 

/***************************•********************************* 

/* Standard include files 

/A************************************************************** 

linclude <string.h> /* String functions */ 

#include <stdlib.h> /* String functions */ 

#include <stdarg.h> /* String functions */ 
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A********************************************************************/ 

/* NetView high level language include files */ 

A********************************************************************/ 

#include "dsic.h" /* Include HLL macros */ 



/ 



******************************************************************* 



/ 



/* External data definitions */ 

/********************************************************************/ 



Dsihlb *Hlbptr; 
Dsivarch *Cmdbuf; 
Dsiorig *0rigblck; 

main(int argc, char *argv??(??)) 
{ 



/* Pointer to the HLB 

/* Pointer to command buffer 

/* Pointer to Origin block 



V 
7 



******************************************************************, 



••••••♦A**********************************************************, 



/ 

/* Internal data definitions 
/ 

/•A****************************************************************/ 

/* Convert parameter pointers from character to hex addresses */ 
/•A****************************************************************/ 

sscanf(argv??(l??),"%x\&Hlbptr); 
sscanf(argv??(2??),"%x , \&Cmdbuf); 
sscanf(argv??(3??),"%x",&0rigblck); 

/******************************************************************/ 

/* Initialization */ 

/••••••A***********************************************************/ 

/******************************************************************/ 
/* */ 

/* Execution */ 

/* */ 

/••A***************************************************************/ 



Cnmvlc(Cmdbuf, 
1, 
"GOOD"); 



/* Set key... 

/* ...convert to hex 

/* ...hex zeroes 



memmove((&(Cmdbuf->buffer??(0??))+2), /* Set rest of key... 
"low rec",7); /* ...move in 7 bytes 



Cmdbuf->size = 9; 
Hlbptr->Hlbrc = USERSWAP; 



/* set new Cmdbuf size 
/* Set USERSWAP re 



V 
V 
V 

V 
V 

V 
V 
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User Exit 



The following is an example of coding a user exit routine dsiexo3 that sets a task 
global variable equal to the last time a command was entered on the system. If the 
last command was the csnddat command, the task global variable will not be set. 
The csnddat command (see "SEND Side" on page 160) is used to interrogate the 
variable value, 

/* V 

/* Descriptive Name: High Level Language PL/I DSIEXG3 Example */ 



/* Change Activity: */ 

/* date, author: description of changes */ 

/* V 

/•it******************************************************** 

#pragma runopts (N0EXEC0PS,N0STAE,N0SPIE t ISASIZE(4K) ,ISAINC(4K)) 

/•A************************************************************ 

/* Standard include files 

/A************************************************************ 

#include <stdlib.h> /* Standard library */ 

#include <stdarg.h> /* Standard args */ 

/* NetView high level language include files */ 

#include "dsic.h" /* Include HLL macros */ 
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********************************************************************, 



/ 

/* External data definitions 



********************************************************************, 



/ 

Dsihlb *Hlbptr; 
Dsivarch *Cmdbuf; 
Dsiorig *0rigblck; 

Dsivarch time; 
Dsivarch cvname; 

main(int argc, char *argv??(??)) 

{ 

***************************************************************** 



/* Pointer to the HLB 

/* Pointer to command buffer 

/* Pointer to Origin block 

/* Time last command entered 
/* Name of variable for Cnmvars 



7 
V 
V 

V 
*/ 



/ 

/* Internal data definitions 
/ 



****************************************************************** 



/ 



/******************************************************************/ 

/* Convert parameter pointers from character to hex addresses */ 

/••••A*************************************************************/ 

sscanf(argv??(l??),"%x",&Hlbptr); 
sscanf(argv??(2??),"%x\&Cmdbuf); 
sscanf (argv?? (3??) , "%x" ,&0rigbl ck) ; 

/A*****************************************************************/ 

/* Initialization */ 

/A*****************************************************************/ 

/•♦•••A************************************************************/ 
/* */ 

/* Execution */ 

/* */ 

/******************************************************************/ 

/* Command other than CSNDDAT? */ 
if (strstr(Cmdbuf->buffer, "CSNDDAT") == NULL) 

{ /* Yes... */ 

CnminfcC'TIME ", /* ...what time is it? */ 

&time, /* ...answer goes here */ 

255); /* ...length of time */ 



} 



Cnmvlc(&cvname, 

0, 
"LAST_COMMAND_TIME"); 

Cnmvars (PUT, 
&time, 
0, 

&cvname, 
TGLOBAL) ; 



Hlbptr->Hlbrc = USERASIS; 
} 



/* Set name of variable... 
/* ...do not convert to hex 
/* ...name of variable 



/* 
/* 
/* 
/* 
/* 



Put answer in task global 
...information in TIME 
...length of time 
...by the name of 
...task global pool 



/* clear re 



*/ 

V 
V 

V 
V 
V 
V 
V 

V 
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Wait for Data 
WAIT Side 



The following is part of an example of sending messages with a type of request, 
waiting on the response, and parsing the results. 

The purpose of the example is to find the last time that a command was entered on 
the given ost. A task global variable, last_command_time is set by dsiexo3, (see 
"User Exit" on page 155) and this value is retrieved by the csnddat command(see 
"SEND Side" on page 160) that is invoked on the target task. The code in this 
example is the cwatdat command. 

The syntax of the command is: 

CWATDAT taskname 

The flow of the wait for data function is: 



OST 



TARGET 
OST 



Invokes 

CWATDAT command 
and specifies the 
target task to 
send the request 



CWATDAT using 
CNMSMSG sends a 
request to the 
OST specified 

OST issues a WAIT 
FOR DATA 



> 



OST wait is 
satisfied — wake up 
and issue message 
to the operator 



CSNDDAT command is 
invoked on the 
OST. It finds the 
task global variable 
set by DSIEX03. 



CNMSMSG type of 

< — DATA is invoked with 

the value retrieved 
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/•A****************************************************************/ 

/* Internal data definitions */ 



/ 



****************************************************************** 



/ 



Dsiorig getblock; 


/* Area for the Orig Block 


*/ 


Dsivarch time; 


/* Time last command entered 


V 


char targtask??(9??); 


/* Task of inquiry 


V 


int len; 


/* length of targtask 


V 


Dsivarch msgbuf; 


/* Message buffer 


*/ 


char *token; 


/* used to parse command 


*/ 



/♦•••••••••••A*****************************************************/ 

/* V 

/* Execution */ 

/* */ 

/♦•••A*************************************************************/ 

token = strtok((char *) &(Cmdbuf->buffer), M "); /* parse command */ 
token = strtok(NULL," "); /* buffer for target task name */ 



if (strlen(token) > 8) 
token = NULL; 

strcpy (targtask, token) ; 

len = strlen(targtask); 
strncat(targtask," 



/* node name invalid 



,8 - len); 



7 



7 
V 



if (token != NULL) /* Was target task entered? 

{ /* Syntax ok... 

if (strncmp(targtask,(char *) &(0rigblck->0rig_task), 
strl en (targtask)) «■» 0) 
{ /* is operator who issued CWATDAT being queried?*/ 

/* put error message in a varying*/ 
Cnmvlc(&msgbuf, /* length character string... */ 

0, /* ...do not convert to hex */ 

"Target task cannot be task invoking CWATDAT"); 



Cnmsmsg(&msgbuf, 
MSG, 
OPER, 
NULLCHAR) ; 

} 
else 

{ 
Cnmvlc(&msgbuf, 

0, 
"CSNDDAT"); 

Cnmsmsg(&msgbuf, 
REQUEST, 
TASK, 
targtask); 



/* 


display the message... */ 


/* 


...the message text */ 


/* 


...type is message */ 


/* 


...send to invoking operator */ 


/* 


...not used */ 



/* Put command in msgbuf 
/* ...do not convert to hex 
/* ...command 



V 

V 
V 



/* Invoke CSNDDAT command 

/* ...type is request 

/* ...on a task */ 

/* ...specified by input command */ 



V 
V 
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Cnmvlc(&msgbuf, /* Put WAIT command in msgbuf 

0, /* ...do not convert to hex 

"WAIT 120 SECONDS FOR DATA"); 



V 
V 



Cnmcmd(&msgbuf); 



/* Invoke WAIT command 



7 



if (Hlbptr->Hlbrc != CNM_DATA_ON_WAIT) /* Wait successful?*/ 
{ /*No... */ 

Cnmvlc(&msgbuf, /* Put error message in msgbuf */ 
0, /* ...do not convert to hex */ 

"Wait for data abnormally ended"); 



Cnmsmsg(&msgbuf, 
MSG, 
OPER, 
NULLCHAR) ; 

} 
else 

{ 
Cnmgetd(GETMSG, 
&time, 
256, 

fcgetblock, 
DATAQ, 
0); 



/* Send error message... 
/* ...type is message 
/* ...to the operator 
/* ...not used 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



Wait was successful 
Process the results 
Read in the response 
...read into time variable 
...give plenty of room 
...provide own origin block 
...on the data queue (3) 
...index not used 



*/ 

V 
V 
7 

*/ 

V 

*/ 

V 

*/ 

V 

*/ 

V 



I****************************************************************** . 



/* 
/* 



Remove process and task id from the buffer !!!! 
First 8 bytes and the last 8 bytes 



V 
V 



f************************************************* 

strncpy (msgbuf. buffer, time. buffer+8, time. si ze-8); 
msgbuf. size = time. size - 8; 



Cnmsmsg(&msgbuf, 


/* 


MSG, 


/* 


OPER, 


/* 


NULLCHAR) ; 


/* 


} 




} 




} 




else 


/* 


{ 




Cnmvlc(&msgbuf, 


/* 


0, 


/* 


"Invalid Target Task"] 


) 


CnmsmsgC&msgbuf, 


/* 


MSG, 


/* 


OPER, 


/* 


NULLCHAR) ; 


/* 



Inform user... 
...type is message 
...to the operator 
...not used 



Target task not entered 

Put error message in msgbuf 
...do not convert to hex 



Inform user of syntax error 
...type is message 
...to the operator 
...not used 



V 
*/ 

V 
V 



V 
V 

*/ 
*/ 

V 
V 
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SEND Side 

The following is part of an example for sending messages with a type of request, 
waiting on the response, and parsing the results. 

The purpose of the example is to find the last time that a command was entered on 
the given task. A task global variable, last_command_time is set by dsiexo3, (see 
"User Exit" on page 155) This value is retrieved by the csnddat command that is 
invoked by the cwatdat command(see "Wait for Data" on page 157) on the target 
task. This command processor is executed when the csnddat command is entered. 
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/••••♦•••••••A**************************************** 

/* Internal data definitions */ 

/•••••••••••♦a************************************* 

Dsivarch time, /* Date the last command was 

/* ...was entered 
msgbuf, /* Buffer for Cnmsmsg 

cvname, /* Buffer for name of variable 

myopid; /* operator id we are running 

/* ...under 



V 

V 
V 
V 

V 
7 



/* */ 

/* Execution */ 

/* 7 

/* determine my opid */ 

Cnminfc("OPID ", /* ...variable is opid */ 

&myopid, /* ...put result here */ 

8); /* ...truncate after 8 bytes */ 

if (strncmp((char *) &(myopid. buffer), (char *) &(0rigblck->0rig_task), 
myopid. size) == 0) 

{ /* CSNDDAT invoked directly? */ 

/* put error message in a varying*/ 

Cnmvlc(&msgbuf, /* length character string... */ 

G, /* ...do not convert to hex */ 

"Cannot issue CSNDDAT directly"); /* CSNDDAT command... */ 

/* ...issued directly */ 





/* display the message... */ 


Cnmsmsg (&msgbuf, 


/* ...the message text */ 


MSG, 


/* ...type is message */ 


OPER, 


/* ...send to invoking operator */ 


NULLCHAR) ; 
} 


/* ...not used */ 



else 
{ 



Cnmvlc(&cvname, /* Set variable name 

0, /* ...do not convert to hex 

"LAST_COMMAND_TIME"); /* ...variable name 



7 
7 
7 



Cnmvars(GET, 
&time, 
256, 

&cvname, 
TGLOBAL) ; 



/* 
/* 
/* 
/* 
/* 
/* 



Retrieve last time variable 
...read in the value 
...into time 
...truncate at 256 
...of the variable 
...in the task global pool 



*/ 

7 
7 
7 
7 
7 
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if (Hlbptr->Hlbrc == CNMJJOOD) /* Variable set? */ 

{ /* Yes, continue... */ 

Cnmvlc(&msgbuf, /* Put data in msgbuf... */ 

0, /* ...do not convert to hex */ 
"%.8sLast command entered at: %.8s M ,/* ...must precede*/ 

Origblck->0rig_process, /* data with origin process id*/ 

time. buffer); /* ...put in time */ 



/* Send data back to requestor 


V 


Cnmsmsg(&msgbuf, /* ...text of message 


V 


DATA, /* ...message is data 


V 


TASK, /* ...to a task 


V 


0rigblck->0rig task); /* ...that invoked this 

} 
else /* No inform user... 

{ 
Cnmvlc(&msgbuf, /* Put error message in msgbuf 


V 


V 


V 


0, /* ...do not convert to hex 


V 


"%.8sMust install DSIEX03 to set time variable", 




Origblck->0rig__process) ; 




/* Send message to requestor 


V 


Cnmsmsg(&msgbuf, /* ...text of error message 


V 


DATA, /* ...message is data 


V 


TASK, /* ...to a task 


V 


0rigblck->0rig task); /* ...that invoked this 
} 


*/ 
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Chapter 10. Compiling, Link-Editing, and Running Your C 
Program 

Once you have a c compiler installed, you can modify the c compile and link-edit 
jcl to use with NetView. The objective of this chapter is to provide the information 
necessary to make these modifications. 

Several examples of compile and link-edit jcl are provided in this chapter. These 
are given as examples only. You are responsible for modifying the compile and 
link-edit jcl samples that were shipped with the c compiler. 

You must have completed the installation steps for hll as described in the NetView 
Installation and Administration Guide before attempting to execute c programs in 
the NetView environment. 



Compiling 



In order to compile c programs using NetView services, it is necessary to modify 
the compile step in the jcl to reference the NetView macro library(s). You will 
need to include in the compile jcl a syslib statement for syslmaclib. An example 
of modifications to compile step jcl is shown below: 

//COMPILE EXEC PGM=EDCCOMP,PARM=('RENT'),REGION=&CREGSIZ 



//SYSLIB DD DSN=SYS1..MACLIB,DISP=SHR 



Link-editing 



The following rules apply when link-editing c modules: 

• All c load modules must be reentrant. 

• c load modules can reside in 24 or 31 bit storage and can be entered in either 
addressing mode. 

• All c load modules must be link-edited with dsihstub and dsiexc. dsihstub must 
be the entry point. 

In order to link-edit a c module to run with NetView, you must modify the link-edit 
step in the jcl to reference the appropriate NetView Library(s). This will allow you 
to include dsihstub and dsiexc at link-edit time. Add syslnvulib and sysllinklib to 
the list of automatic call libraries already defined by syslib in the c link-edit step of 
the jcl. An example is shown. 
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//LKED EXEC PGM IEWL, 

// PARM= , XREF,RENT,LET,LIST,AMODE=&AMODE,RMODE=&RMODE' , 

// REGI0N=4096K,C0ND=(8,LE, COMPILE) 



//SYSLIB DO DSN=SYS1.NVULIB,DISP=SHR 

// DD DSN=SYS1.LINKLIB,DISP=SHR 



INCLUDE 


SYSLIB(DSIHSTUB) 


INCLUDE 


SYSLIB(DSIEXC) 


ORDER 


DSIHSTUB 


ENTRY 


DSIHSTUB 


MODE 


AM0DE(31),RM0DE(ANY) 


NAME 


LMODNAME(R) 



Note: All hll modules must be compiled and link-edited with the rent option. For 
ibm c/370, you will have to execute the pre-linkedit step and code the rent compiler 
option. The resulting object deck(s) must then be link-edited with the rent option. 



Running 



A set of run-time libraries will be shipped with the compiler. In order to execute a 
c program in the NetView environment, you must modify your NetView start up pro- 
cedure to reference the appropriate c run-time libraries. Refer to the NetView 
Installation and Administration Guide for more information. 



hll command processors require a cmdmdl statement in member dsicmd of the 
dsiparm data set. User exits are loaded at initialization and need to conform to 
user exit naming conventions. For more information on user exits see Chapter 2 
on page 9. 
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Part 4. HLL Debugging and Service Routine Reference 

Chapter 11. Testing And Debugging 167 

Remote Interactive Debugger (RID) -167 

Using RID to Monitor a Task 167 

RID Command 167 

Remote Interactive Debugger RID Scenarios 169 

Chapter 12. Command and Service Reference 173 

Notational Conventions 173 

Composite Return Codes 174 

Command Reference 177 

GO Command 177 

QUEUE Command 179 

RESET Command 180 

TRAP Command 183 

WAIT Command 186 

HLL Service Routine Reference 190 

CNMALTD (CNMALTDATA) - Alter Data On A Queue 190 

CNMCELL (CNMSTRCELL) - Storage Cell 193 

CNMCMD (CNMCOMMAND) - Execute NetView Commands 195 

CNMCNMI (CNMI) - CNMI Access Under a DST 199 

CNMCPYS (CNMCOPYSTR) - Copy Storage 201 

CNMGETA (CNMGETATTR) - Query Message Attributes 203 

CNMGETD (CNMGETDATA) - Data Queue Manipulation 206 

CNMINFC (CNMINFOC) - Query NetView Character Information 209 

CNMINFI (CNMINFOI) - Query NetView Integer Information 211 

CNMKIO (CNMKEYIO) - Keyed File Access Under a DST 213 

CNMLK (CNMLOCK) - Control A Lock 216 

CNMMEMO (CNMOPENMEM) - Open NetView Partitioned Data Set .... 218 
CNMMEMR (CNMREADMEM) - Read NetView Partitioned Data Set .... . 220 
CNMMEMC (CNMCLOSMEM) - Close NetView Partitioned Data Set .... 222 

CNMNAMS (CNMNAMESTR) - Named Storage 223 

CNMPOOL (CNMSTRPOOL) - Storage Pool 226 

CNMSCAN (CNMSSCAN) - Parse and Convert a Character String-(PL/I) . 229 

CNMSCOP (CNMSCOPECK) - Scope Check for Security 232 

CNMSMSG (CNMSENDMSG) - Send Message or Command 234 

CNMVARS (CNMVARPOOL) - Set or Retrieve Variables 238 



i 
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Chapter 11. Testing And Debugging 



It is assumed that your hll module has been compiled and link-edited successfully 
upon entry into this chapter. Upon completion of this chapter, the user should be 
familiar with the NetView Remote Interactive Debugger (rid) and how it can be 
used to debug hll programs. 



Remote Interactive Debugger (RID) 



NetView's Remote Interactive Debugger (rid), gives you the ability to checkpoint 
entry and exit parameters to hll service routines and display storage at various 
predetermined debug points in the code. 

Using RID to Monitor a Task 

NetView's interactive debug facility gives you the ability to monitor and debug hll 
modules during execution. It is necessary to determine a monitoring task and a 
target task to debug hll modules effectively. The monitoring task must be an ost. 
It is from this task that you will issue the rid commands which control the execution 
of the hll module running under the target task. The target task may be an ost, 
ppt, nnt, or a DST. 

rid begins to monitor the target task immediately after the rid command is issued 
from the monitoring task. If rid is invoked in step mode the monitoring task con- 
trols the execution of the hll module running under the target task. The monitoring 
task will continue to control the execution of hll modules running under the target 
task until rid is invoked with the run or end option. 

The most common use of the debugger is the default option which will display 
parameters upon entry to (hapientr) and exit from (hapiexit) hll service routines. 



RID Command 



The following syntax describes the rid command as it is issued from the monitoring 
or debugging task. 



RID TASK = opid 

[,STEP|RUN|CONTiNUE|END] 

[,MODNAME=!|name] 

[.OPTION = *|HAPIENTR|HAPIEXIT] 



Where: 

STEP 

When the step option is specified, the target task will be stopped whenever 
control is given to a debug point that matches the criteria specified by the 
modname or option operand. Messages providing data captured at the debug 
point are displayed at the operator station that invoked rid to monitor the target 
task, step is the default. 
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RUN 

The run option is similar to the step option, except that the target task con- 
tinues to execute after issuing the messages at the debug point(s). The run 
option will resume execution of a task stopped in step mode. 

CONTINUE 

The continue option is used to resume execution of a task that was stopped by 
the step option of rid. New debug point match criteria may be specified in con- 
junction with the continue option. The continue keyword is provided for read- 
ability only. Execution can be resumed by reissuing the rid command with its 
original operands. 

END 

The end option will cause rid debugging of a task to cease and allow other 
operators to invoke rid for the target task. If the target task is stopped and rid 
is invoked with the end option, the hll program running under the target task is 
resumed. 

MODNAME 

Name of the module being monitored by rid. If * is specified, rid will monitor 
all hll programs running under the target task. * is the default. 

OPTION 

Specifies the type of debug point. * is the default. 

* All debug points will be displayed. 

HAPIENTR Entry to hll api service routine 

HAPIEXIT Exit from hll api service routine 

Usage Notes: 

A NetView task can only be monitored (using rid) by one NetView operator at a 
time. 

It is not recommended to use rid to monitor or debug hll command processors 
running under the ppt. Running rid against the ppt causes the ppt to get sus- 
pended which could cause undesirable results if timer sensitive functions (such as 
at or every) are being performed. 

The user is required to code a list of parameters for each hll service routine invo- 
cation. When activated, rid will display these parameters and their values on entry 
to and exit from each hll service routine. The maximum number of data fields that 
rid is capable of displaying is ten. This is important when using rid to monitor 
calls to and from cnmscan. The user can specify a maximum of 14 arguments on a 
call to cnmscan. This means that the user may not be able to view the complete 
parameter list when monitoring cnmscan invocations. 

The default value (*) for modname and option will be used until a value is specified. 
Once a value has been specified, it will be used on all successive rid invocations 
unless explicitly overridden, modname and option will be reset to the default values 
once rid is invoked with the end option. 
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Return Codes: 



CNM_GOOD 





Everything OK 


CNM_NOT_FOUND 


20 


Task not found 


CNM_NO_STORAGE 


24 


Non-zero return code from 
dsiget macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsiget 
macro). 


CNM_BAD_OPTION 


128 


Invalid option 


CNM_BAD_TASKNAME 


164 


Task name too long 


CNM_BAD_MODNAME 


168 


Module name too long 


CNM_BAD_COMBO 


176 


Invalid combination of 
options 


CNM_TVB_INUSE 


180 


tvb in use 


CNM_RID_INUSE 


184 


rid in use 


CNM_RID_SELF 


188 


Debug task and target task 
can not be the same. 


CNM_BADJ>USH + X 


4000 + X 


Non-zero return code X 
from dsipush macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsipush 
macro). 


CNM_BAD_SNTXS + X 


17000 + X 


Non-zero return code X. 
See values for X below. 



Values for X: 





4 


Invalid syntax. 



Remote Interactive Debugger RID Scenarios 



The following scenario describes how rid can be used to monitor or debug an hll 
module. For the purpose of this example, we have assumed that the user has 
chosen to debug an hll program that has already been compiled and link-edited 
into NetView. The process for debugging hll modules written in c and pl/i are 
similar except for some slight differences in the rid panels that are displayed. For 
this example, yourpgm is the name of the hll command processor that will be mon- 
itored while executing under target task operl OPER2 has been chosen as the mon- 
itoring or debugging task. 

Invoke rid by issuing the following command from OPER2: 
RID TASK=0PER1 

The following shows the system response, rid defaults to step mode operation. 
Execution of yourpgm will be halted at each debug point. 
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;■• .'■" . -. 0PER2 

~ CNMet-,.. CNM986I RI& FUNCTION 'STEP* COMPLETED FOR TASK GPER1 



From OPER1, type the name of the hll program which you have chosen to debug. 

YOURPGM 

The following screen is displayed on oper2's console. This is the entry screen 
(hapientr) for your pl/i program (id=plientry). The id for the entry screen for a c 
program is centry. 



^1^^^^^^^^^^^^^^^^^^*^^ 



CNM987I TASK 0PER1 MOB YOURPGM TYPE HAPIENTR ID PLIENTRY SEQ 1 

CNM988I MVT 00007088 TVB 000278F9 TIB 00067338 TR8 0258B9D0 R13 0265EBB8 

HLBPTR H 4 0258BA48 0258BA92 

BUFFER S 7 0258BOF6 YOURPGM 

ORISBLCiC C 42 0258BA60 * CNM01 0PER1 

ISASIZ U 4 025889EC 4000 

HEAPSI2 U 4 0258BA00 512 

PLI0PTS ft. 4 0258BA38 55680000 



O HI 1 



??? 



Figure 5. PL/I Entry Screen for YOURPGM 

The numbered boxes in Figure 5 are described as follows: 
Q Message CNM987I displays the following information: 

TASK 

Name of the target task being monitored by rid 

MOD 

Name of the module being monitored by rid 

TYPE 

Type of debug point currently being displayed 

10 

Unique identifier for the debug point being displayed. 

SEQ 

The sequence number of this rid panel. 

Q Message CNM988I displays the addresses of the mvt, tvb, tib, 

trb, and the contents of Register 13 which points to your 
savearea. mvt, tvb and tib are described in the control block 
reference section of the NetView Customization: Assembler 
manual, trb is the Transaction Block and is used only by ibm 
service. 
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Q hlbptr, buffer, origblck are the initial parameters passed to 

your command processor from NetView. isasiz, heapsiz and 
pliopts are the default pl/i run-time values unless you have 
overridden these values in your hll program. 

Q Describes how each of the variables in is declared: H-Hex, 

D-Dump, C-Character, S-String, U-Unsigned, Mnteger 
A-Address. 

Qj Lengths of the variables in Q that are expected by the hll 

service routines. 

Q Addresses in storage where the values for the variables in Q 

are stored. 

Q Values associated with each of the variables in Q. 

Continue to the next debug point by entering the following rid command from 

OPER2I 

RID TASK=0PER1, CONTINUE 

Since option was not specified, rid will display panels upon entrance to (hapientr) 
and exit from (hapiexit) all hll service routines invoked from /* the hll program 
being debugged. In Figure 6, rid is displaying the parameters on entry to 
(hapientr) the cnmsmsg service routine. The parameters for each hll service 
routine are explained in Chapter 12. 



-..,. .............. .. .. ..;.,.. ., . ....... ., ... 0f>£R2 

i-CNM987I TASK 0PER1 MOD YOURPGM TYPE HAPIENTR 10 SENDMSGE SEQ 2N 

ICNM988IMVT 098Q7D88 TVB 0O027BFO TIB 80067338 TRB 0258BAE6 R13 0258BC18 S 

^SMTEXT S 25 0O0697CE HELLO 

ISMMSGTYPC 8 609697EC MSG 

fSMDESTYPG 8 009697F4 OPER 

ISMDESTID C 8 800697FC 



??? 



K* A«*r^'-iS5*^*>i-- « 



Figure 6. Entry Screen for CNMSMSG 

Continue to the next debug point by entering the following rid command from 

OPER2: 

RID TASK=0PER1 

Notice that it is not necessary to issue the rid command with the continue operand 
when you want to resume execution of a task, continue is used for readability. 
Figure 7 on page 172 displays the parameters on exit from the cnmsmsg service 
routine. Note that retcode has been added, retcode is the value of hlbrc (Hlbrc 
for c programs) on exit from an hll service routine. 
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GPERZ 

CNM987I TASK OPERl MOD YOURPGM TYPE HAPIEXIT ID SENDMSGX SEQ 3 » 

CNM988I MVT 00O07D88 TVB 0O027BF0 TIB 00067338 TRB 0258BAE6 R13 0258BC18 S 

SMTEXT S 25 00O697CE HELLO 

SMMSGTYP C 8 0O0697EC MSG 

SMDESTYP C 8 000697F4 OPER 

SMOESTID C 8 800697FC 

RETCODE I 4 0258BCB4 +0 

??? 



Figure 7. Exit Screen for CNMSMSG 

Continue to the next debug point by entering the following rid command from 

OPER2: 

RID TASKOPER1 

The final rid panel displayed in Figure 8 is a pl/i exit panel that corresponds to the 
plientry panel in Figure 6 on page 171. Notice that type= hapiexit and id=pliexit. 
If this were a c program, id would be cexit. Notice that retcode has been added but 
isasiz, heapsiz and pliopts are no longer displayed. 



0PER2 



CNM987I TASK OPERl MOD YOURPGM 


TYPE HAPIEXIT ID PLIEXIT 


SEQ 3 N 


CNM988I MVT 


00007D88 TVB O0O27BF0 


TIB 00067338 TRB 0258B9D0 


R13 0265EBB8 S 


HLBPTR h 


4 0258BA48 0258BA92 






BUFFER S 


7 0258BDF6 YOURPGM 






ORIGBLCK C 


42 0258BA60 * 


CNM01 OPERl * 




RETCODE I 


4 0265EB4C +0 







??? 



Figure 8. PL/I Exit Screen for YOURPGM 
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Chapter 12. Command and Service Reference 



This chapter assumes that you have an understanding of the information discussed 
in the previous chapters. Upon completion of this chapter, you should have an 
understanding of each of the hll commands and service routines and their associ- 
ated parameters. 

It primarily contains general-use programming interfaces, which allow the cus- 
tomer to write programs that use the services of NetView. However, this chapter 
also provides the following types of information, which are explicitly identified 
where they occur: 

Installation exits and other product-sensitive interfaces are provided to allow the 
customer installation to perform tasks such as product tailoring, monitoring, mod- 
ification, or diagnosis. They are dependent on the detailed design or implementa- 
tion of the product. Such interfaces should be used only for those specialized 
purposes. Because of their dependencies on detailed design and implementation, 
it is to be expected that programs written to such interfaces may need to be 
changed in order to run with new product releases or versions, or as a result of 
service. 



Notational Conventions 



The following notational conventions apply to the commands and service routines 
described in this chapter. 

lowercase item 

Lowercase bold-faced letters represent parameters for which you must 
supply the value, address, or name, rather than the literal information. 

UPPERCASE item 

Uppercase bold-faced letters represent the valid literal values for a 
specified parameter. 

underscored item 

An underscored item represents the default value of a particular param- 
eter. If you specify no parameter, NetView uses the default value. 

Braces { } 

Small braces enclose the different options for a parameter. Large 
braces enclose mutually exclusive parameters; you must select one, 
and only one, of these parameters. Do not include the braces when 
coding the information. 

Brackets [ ] 

Brackets enclose an optional parameter. Optional parameters can be 
included or omitted independently of other parameters. Do not include 
the brackets when coding the information. 



OR-sign | 



The OR-sign separates the options for a required (brace-enclosed) 
parameter or for an optional (bracket-enclosed) parameter. For a 
required parameter, one of the options must be coded. For an optional 
parameter, none of the options have to be coded. Do not type the 
OR-sign when coding the information. 
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Composite Return Codes 



Most of the NetView commands, command lists, and High-Level Language (hll) 
service routines generate return codes upon completion. There are two types of 
return codes; simple and composite. A simple return code is a constant value that 
requires no computation. A composite return code is a calculated value that con- 
sists of known (constant) and one or more unknown values. 

The return code section at the end of each hll command and service routine pro- 
vides a chart of the following: 

1. the return code represented in terms of constants and unknown values (if 
applicable) 

2. the return code represented in terms of resolved constants and unknown 
values (if applicable) 

3. a description of why the return code was issued. 

Several of the descriptions will refer the user to a NetView macro. Each of these 
macros is referenced in NetView Customization: Using Assembler. 

The unknown values of a composite return code can be resolved in the following 
manner. 

1. Start with the following equation: 

HLBRC = Composite return code equation 

2. Resolve all known values. The first and most obvious known value is that of 
hlbrc. All other known values are represented as constants in dsipcnm (see 
Appendix A) and dsiccnm (see Appendix C). In the case where there is more 
than one unknown value to resolve (x and y), the remaining calculated value 
will be split into a major and minor return code. 

Example (1) 

Upon completion of a call to cnmnams, hlbrc=4004. A return code value in the 4000 
range implies that the composite return code equation is: 

CNM_BAD_PUSH + X 

After resolving the known values, we see that the unknown value X, is equal to 4. 
The user should refer to the return code section of cnmnams, which would indicate 
that the return code was actually generated by the dsipush macro. See this macro 
in NetView Customization: Using Assembler for the description of the return code. 

HLBRC = CNM_BAD_PUSH + X 
4004 = 4000 + X 
4004 - 4000 = X 
4 = X 
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Example (2) 

Upon completion of a call to cnmcmd, hlbrc=-3108. A return code value in the -3000 
range implies that the composite return code equation is: 

X - CNM_BAD_EXCMS 

Resolve the known values: 

HLBRC = X - CNM_BAD EXCMS 
-3108 = X - 3000 
-3108 + 3000 = X 
-108 = X 

A value of -108 for X implies that X = SWBEXCNF - Y. (See the return code section 
of cnmcmd.) After resolving the known values, the user will see that the unknown 
value Y, is 8. The user should again refer to the return code section of cnmcmd 
which would indicate that the return code was actually generated by the dsices 
macro. See this macro in NetView Customization: Using Assembler for the 
description of the return code. 

-108 = SWBEXCNF - Y 
-108 = -100 - Y 
-108 + 100 = -Y 
-(-108+100) = Y 
8 = Y 



Example (3) 

Upon completion of a call to cnmcnmi, hlbrc=21600. A return code value greater 
than 20000 for cnmcnmi implies that the composite return code equation is: 

CNM_BAD_ZCSMS + (X * 100) + Y 

After resolving the known values, the user will see that the unknown values X and 
Y are 16 and respectively. The user should refer to the return code section of 
cnmcnmi which would indicate that the return code was actually generated by the 
dsizcsms macro. See this macro in NetView Customization: Using Assembler for 
the description of the major and minor return codes. 

HLBRC = CNM_BAD ZCSMS + (X * 100 ) + Y 

21600 = 20000 +~(X * 100) + Y 

21600 - 20000 = (X * 100 ) + Y 

1600 = (X * 100) + Y 

=> 1600 / 100 

MAJ0R_RC is the quotient => 16 
MIN0R_RC is the remainder => 

This can also be seen visually: 

16 00 => 16 = MAJ0R_RC 
00 = MINOR RC 
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Example (4) 

Upon completion of a call to cnmcnmi service routine, hlbrc=20408. A return code 
value in the 20000 range implies that the composite return code equation is: 

CNM_BAD_ZCSMS + (X * 100) + Y 

After resolving the known values, the user will see that the unknown values X and 
Y are 4 and 8 respectively. The user should refer to the return code section of 
cnmcnmi which would indicate that the return code was actually generated by the 
dsizcsms macro. See this macro in NetView Customization: Using Assembler for 
the description of the major and minor return codes. 

HLBRC = CNM_BAD_ZCSMS + (X * 100 ) + Y 
20408 = 20000 + (X * 100) + Y 
20408 - 20000 = (X * 100 ) + Y 
408 = (X * 100) + Y 

=> 408 / 100 

MAJ0R_RC is the quotient => 4 
MIN0R_RC is the remainder => 8 

This can also be seen visually: 

4 08 => 4 = MAJ0R_RC 
8 = MIN0R_RC 

Example (5) 

Upon completion of a call to cnmkio, hlbrc=28692. Only two composite return codes 
are issued from cnmkio. See the return code section of cnmkio. Since the return 
code value is NOT in the 2000 range (this would indicate a dst failure), the value of 
28692 implies that the composite return code equation is: 

(CNM_BAD_ZVSMS + X) * 256 + Y 

This equation is difficult to resolve without knowing either x or y. Use the following 
equations to determine the major and minor return codes: 

MAJ0R_RC = (HLBRC / 256) - 100 

= (28692 / 256) - 100 (keep only the quotient) 

= 112 - 100 

= 12 

MIN0R_RC = HLBRC - ((CNM_BAD ZVSMS + MAJ0R_RC) * 256) 

= 28692 - ((100 + 12) * 256) 

= 28692 - (112 * 256) 

= 28692 - 28672 

= 20 

You should refer to the return code section of cnmkio which would indicate that the 
return code was actually generated by the dsizvsms macro. See this macro in 
NetView Customization: Using Assembler for the description of the major and 
minor return codes. 
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Command Reference 



GO Command 



The following commands are useful when executing hll command processors. The 
go, queue, and reset commands are operator commands and may be issued from 
the operator console or from an hll command processor via cnmcmd. The trap and 
wait commands must be issued from within an hll command processor via 
cnmcmd. Refer to NetView Customization: Writing Command Lists for information 
about using trap and wait in a command list. 



The go command allows you to resume running a command procedure that is in a 
pause or wait state. You can also use the go command to pass values to a 
command procedure that is in a pause state. 

HLL Usage Notes 

The go command can be entered from a terminal to satisfy a wait or pause. A 
return code of cnm_go_on_wait will be generated when go is entered in the fol- 
lowing situations: 

1. The event specified on the wait command is messages (timer may or may not 
be set) 

2. The event specified on the wait command is data (timer may or may not be set) 

3. The timer is set for the wait command with no specified events. 

A return code of cnm_opinput_on_wait will be generated if one of the events speci- 
fied on the wait command is opinput. go may be entered alone or operator input 
may follow the go. See "WAIT Command" on page 186 for more information on 
satisfying a wait. 
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Return Codes: 



CNMJ300D 





Everything OK. 


CNM_NO_STORAGE 


24 


Non-zero return code from 
the dsiget macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsiget 
macro). 


CNM_BAD_MQS + X 


1000 + X 


Non-zero return code (X) 
from the dsimqs macro. 
(See NetView 
Customization: Using 
Assembler for more infor- 
mation on the dsimqs 
macro). 


CNM_BAD_LCS + X 


13000 + X 


Non-zero return code (X) 
from the dsilcs macro. 
(See NetView 
Customization: Using 
Assembler for more infor- 
mation on the dsilcs 
macro). 



Refer to NetView Operation for more information on the go command. 
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QUEUE Command 

The queue command adds a text message to the operator input queue (operq) of an 
hll command processor or user exit routine running with the hll queued input bit 
of hllopts turned on. 

Return Codes: 



CNM_GOOD 





Everything OK. 


CNM_NO_STORAGE 


24 


Non-zero return code from 
the dsiget macro. 


CNM_BAD_MQS + X 


1000 + X 


Non-zero return code (X) 
from the dsimqs macro. 



Refer to NetView Operation for information about the queue command. 
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RESET Command 

High-level language support gives the user the option of specifying whether or not 
a command procedure is cancellable. Refer to the hll run-time options (hllopts) 
section of this manual for further detail. 

If a command procedure is cancellable, it will behave according to the rules speci- 
fied under the reset command in the NetView Operations manual. The description 
for reset normal states that a command will be stopped at its next break point 
whenever reset normal is issued. A break point occurs in an hll command proce- 
dure whenever an hll service routine is invoked. 

If a cancellable command procedure is reset via reset normal, it will terminate 
with a -5 return code, which will in turn, cancel its caller if the caller is also 
cancellable. 

If the command procedure is non-cancellable, it will only be reset when reset 
immed and reset dump are issued. In the case where reset normal is issued, reset 
will behave as follows: 

Whenever reset is issued, NetView turns on a "reset flag" which remains on until it 
is acted upon (a command procedure is reset). So, if reset normal is issued while a 
non-cancellable command procedure is running, the reset flag will remain on until 
the non-cancellable command procedure either calls or returns to a cancellable 
command procedure or uses the cnminfi service routine to check resetreq. 

A non-cancellable command procedure can check to see if an operator has 
attempted to reset it by using the resetreq function of the cnminfi service routine. 
If a command procedure uses cnminfi to check resetreq, the reset flag is set off 
and the decision to cancel becomes the responsibility of the command procedure 
checking resetreq. If the command procedure wishes to cancel itself, it must do so 
by returning with a -5 return code. If the command procedure terminates with a -5 
return code, it will also cancel its caller if the caller is cancellable. If the caller is 
not cancellable, however, the caller will not be cancelled and the reset flag will not 
be set on. The reset flag is only set on as a result of reset, logoff, or close immed 
being issued. 

Note: In the following examples, boxes represent command procedures, the 
words "can be cancelled" within the boxes means the command procedure is 
cancellable, and the words "cannot be cancelled" within the boxes means the 
command procedure is non-cancellable. 

Examples: 

In the following example, cancellable command procedure x calls cancellable 
command procedure y which calls cancellable command procedure z. reset 
normal is entered while command procedure z is running. 
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Procedure 
X 

(can be 
cancelled) 




Procedure 
Y 

(can be 
cancelled) 




Procedure 
Z 

(can be 
cancelled) 






(RC=-5) 


(RC=-5) 


(reset) 




(reset) 




(reset 
entered) 



Figure 9. Example 1 of Command Procedure Cancelling 

As a result of entering reset normal, z is reset, z returns -5 to y, y is reset, y returns 
-5 to x, and x is reset. 

Keep in mind that the hll command procedures have to invoke hll service routines 
in order for the reset bit to be checked. So, y and x will continue executing if they 
do not invoke any more hll service routines. 

In the following example, cancellable command procedure x calls non-cancellable 
command procedure y which calls cancellable command procedure z. reset is 
entered when command procedure z is running. 



Procedure 
X 

(can be 
cancelled) 




Procedure 
Y 

(cannot be 
cancelled) 




Procedure 
Z 

(can be 
cancelled) 








(RC=-5) 



(not reset) 



(not reset) 



(reset entered) 



Figure 10. Example 2 of Command Procedure Cancelling 

As a result of entering reset normal, z is reset, y receives a -5 return code from 
the call to z. 

In the following example, non-cancellable command procedure x calls non- 
cancellable command procedure y, non-cancellable command procedure y returns 
control to non-cancellable command procedure x, and non-cancellable command 
procedure x then calls cancellable command procedure z. Reset is entered just as 
x begins execution. 
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Procedure 
X 

(cannot 
be cancelled) 




Procedure 
Y 

(cannot 
be cancelled) 








(not reset) 




Procedure 
Z 

(can be 
cancelled) 




(RC=-5) 



(reset entered) 



(reset) 



Figure 11. Example 3 of Command Procedure Cancelling 

As a result of entering reset normal, x is not cancelled because it is non- 
cancellable, x goes ahead and calls y, y is not cancelled because y is non- 
cancellable, y returns control to x, and then x calls z which is reset, z returns 
control to x with a -5 return code. In this case, the reset flag was turned on when 
the user tried to reset x but was not turned off until it was acted upon, (z was reset) 

In the previous example, command procedure x could have checked the reset flag 
using the hll service routine cnminfi. If x had done this, the reset flag would have 
been turned off and z would not have been reset. 

IMPORTANT: It is recommended that you make your command procedures 
cancellable whenever possible. The non-cancellable option of high-level language 
support has been provided so that a user can code command procedures to do 
cleanup (such as free storage) before being cancelled. 

Note: When a High-level language command procedure is cancelled, the clean-up 
done is equivalent to that done by stop in pl/i and exit in c. See your pl/i or c 
manual to see what cleanup is done for you in these cases. 

Recommended scenario when cleanup is needed: 



Procedure 



(cannot be 
cancelled) 



(not reset) 



(RC=-5) 



Procedure 



(can be 
cancelled) 



(reset entered) 



Figure 12. Example 4 of Command Procedure Cancelling 

In this scenario, if reset is issued while y is executing, y will be terminated and X 
will stick around to do cleanup. 
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TRAP Command 



The trap command lets the user specify message trapping criteria for hll and rexx 
command procedures designed to trap messages. Once issued, all subsequent 
messages that match the conditions defined by the trapping criteria will be added 
to the message queue (trapq). When used in conjunction with the wait for mes- 
sages command and the cnmgetd service routine, the trap command allows the 
user to code command procedures to intercept and process (automate, display, 
suppress, etc.) certain messages. The message trapping criteria specified in the 
trap command defines the set of conditions that will satisfy subsequent wait for 
messages commands, trap can only be issued from command procedures written 
in a high-level language or rexx. All operands are order dependent. 



■'^^^.''^^.r^f^f'^^r^v^.y^ 



TRAP [[AND]{SUPPRESS|D|SPLAY}3 
[{MOREjONLY}] 
MESSAGES [domainidl .]token1 \£domainid2.] token2...'] 

OR 

TRAP NO MESSAGES 



Where: 

AND 

Can be used to make the trap command more readable. You can only use and 
between trap and suppress or trap and display. 

SUPPRESS IPJSPLAY 

SUPPRESS Indicates that any message matching a specified token 

should not be displayed on the operator's screen when 
received by NetView. 

DISPLAY Indicates that any message matching a specified token 

should be displayed on the operator's screen when 
received by NetView. display is the default. 

MOREI ONLY 

MORE Indicates that the specified tokens should be added to the 

list of tokens that was specified on a previous trap 
command. 

Note: Each message in the resulting list retains its own 
individual setting of the suppressi display option. This will 
allow some messages in the list to be suppressed while 
others are displayed. 

ONLY Indicates that the specified tokens replace the list of tokens 

on a previous trap command, only is the default. 

MESSAGES 

This is a required operand which indicates that the trapped items are mes- 
sages, domainid (1 to 8 characters) is the domain id of the message or mes- 
sages to be trapped, token (1 to 10 characters) identifies the first token of the 
message or messages to be trapped. Most special characters are valid for 
token. However, the equal sign ( = ) is invalid for token and will result in a 
syntax error. There is no limit on the number of tokens that can be specified. 
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NO 



Note: You may use a trailing asterisk (*) in the domainid or token as a 
wildcard character. Asterisk (*) can also be used as a character in a token. 

For example, trap messages a*b* traps on tokens beginning with a*b followed by 
any characters. If the (*) is followed by a character, then it is considered to be 
part of the token. 

Indicates that the list of tokens that was specified on all previous trap com- 
mands should be removed, trap no messages will clear the command proce- 
dure's list of messages to trap. No other operands are valid with no. 

Following are examples of how you can specify the messages you want to trap: 

domainid. token The command procedure traps any message whose 

domain identifier matches the 1 to 8 character 
domainid, and whose first token matches token. 

dom*. token The command procedure traps any message whose 

domain identifier matches the partial domain identifier 
specified by dom* and whose first token matches 
token. For example, nccf*.dsi604i means trap a osi604i 
message from any domain with an identifier that starts 
with nccf (such as nccfa or nccfb). 

*. token The command procedure traps any message whose 

first token matches token. The message can be from 
any domain. 

token The command procedure traps any message whose 

first token matches token, {domainid is assigned the 
wildcard character (*)). 

tok* The command procedure traps any message whose 

first token matches the partial token specified by tok*. 
For example, dsi* means trap any messages whose 
first token begins with dsi, such as DSI604I or dsio28i. 



The command procedure traps all messages. 



Usage Notes: 



Each trap command without the more operand cancels and replaces the previous 
trap command. To add tokens to a previous trap command, use the more 
operand. 

The issuance of a trap command does not clear the queue of messages trapped by 
the previous trap command. To clear the message queue, issue a flushq (See 
"CNMGETD (CNMGETDATA) - Data Queue Manipulation" on page 206). 

The trap command must be issued from a command procedure running under an 
ost or nnt. 

Immediate messages are not trapped; they will not be added to the message queue 
(trapq). 

trap and suppress messages * is NOT the same as TRAP no messages, trap and sup- 
press messages * traps all messages but does not display them on the operator's 
console. 
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Message trapping (trap command) takes precedence over message automation. 

When trapping taf messages, the domain id is actually the session id for that taf 
session. 

Return Codes: 



CNM_GOOD 





Everything OK. 


CNM_BADJNVOCATION 


4 


trap was NOT issued from 
an hll or rexx command 
procedure. 


CNM_BAD_SYNTAX 


12 


Syntax error. When DS1028I 
is issued, check 
domainid.token syntax. 
When DSI604I is issued, 
check the format of the trap 
command according to the 
operand specified. 


CNM_BAD_COMMAND 


144 


trap was NOT issued from 
a command procedure 
running under an ost or 

NNT. 


CNM_BAD_MRBLD + X 


18000 + X 


Non-zero return code X. 
See values for X below. 



Values for X: 





8 


Request for storage has 
failed. 
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WAIT Command 

When issued from a command procedure, the wait command will temporarily 
suspend processing of that command procedure until a specified event occurs. For 
an hll command procedure, the event can be (1) one or more messages, (2) oper- 
ator input, (3) data, (4) a certain period of time, or any combination of the four. The 
first occurrence of one of these events will satisfy the wait and processing will be 
resumed. 

WAIT [n [{SECOJNDSIMINUTES}]] 
[[FOR] event[event...]] 

..•'.••'...'.pR .."*';■ v.V'.V/: .; ;• .;:;..;; 

WAIT CONTINUE 

where: 

n 

The number of seconds or minutes that the command procedure waits for 
receipt of the messages specified on the trap command, receipt of operator 
input, or receipt of data before processing is resumed. The command proce- 
dure may also wait only for the specified time (no specified events) before 
processing is resumed. Valid ranges for n are to 2,678,400 and to 44,640 for 
seconds and minutes respectively. 

SECONDS|MINUTES 

SECONDS The specified unit of time is seconds. 

MINUTES The specified unit of time is minutes. 

FOR 

Can be used to make the wait command more readable. 

event 

The event or events that the command procedure is waiting for. 

MESSAGES The command procedure waits for one or more messages 

before processing is resumed. The message criteria is 
specified using the trap command. See "TRAP 
Command" on page 183. 

OPINPUT The command procedure waits for operator input. Both 

the queue and go command queue data to the operator 
input queue. See "GO Command" and "QUEUE 
Command" on page 179 of this manual. 

DATA The command procedure waits for data sent by cnmsmsg 

with smmsgtyp = data. See "CNMSMSG (CNMSENDMSG) 
- Send Message or Command" on page 234. 

CONTINUE 

Continue waiting for additional messages, operator input, or data before 
command procedure processing is resumed. 

Usage Notes: 

In rexx, only messages are valid events. 
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The NetView operator's screen is refreshed whenever a message arrives or the 
enter key is pressed. If the screen is refreshed while an hll command procedure 
is in a wait state, the pause and wait status indicators (p and w) are displayed in 
the upper right hand corner of the current command facility screen. The w indi- 
cator notifies the operator that the command procedure has halted its processing 
and is waiting for one or more messages, data, or a specified period of time. The p 
indicator notifies the operator that the command procedure has halted its proc- 
essing and that one of the events it is waiting for is operator input. When the wait 
is satisfied, processing resumes and the indicators are cleared from the screen. 

The operator input queue should always be flushed (flushq) after a wait command 
has been satisfied with operator input. Otherwise, subsequent wait for opinput 
commands will not wait for operator input. See "CNMGETD (CNMGETDATA) - 
Data Queue Manipulation" on page 206 for more information on flushq. 

The wait command can only be issued from an hll or rexx command procedure 
running under an ost or nnt. 

The wait command with no operands is invalid. 

The following example illustrates the use of the trap and wait commands. If the 
initial wait command is satisfied after 5 seconds, the wait continue command will 
get control and the command procedure will continue to wait for the remainder of 
the time specified (15 seconds) in the previous wait command. 

CNMCOMMAND DATA ('TRAP MESSAGES MSG1 MSG2 MSG3'); 

/* Trap messages with tokens MSG1, MSG2, MSG3 */ 

CNMCOMMAND DATA('WAIT 20 SECONDS FOR MESSAGES'); 

/* Wait up to 20 seconds for the first trapped message */ 
CNMGETDATA FUNC(FLUSHQ) QUEUE(TRAPQ); 

/* Remove messages from the message queue */ 

CNMCOMMAND DATA ('WAIT CONTINUE'); 

/* Continue waiting for the next trapped message */ 

Unlike rexx, an hll command procedure that issues the wait continue command 
can continue waiting for operator input and data. The following example illustrates 
this. If operator input is received within 12 seconds, the first wait will be satisfied 
and the command procedure will continue to wait for operator input for the 
remaining 18 seconds. The same is also true when waiting for data. 

CNMCOMMAND DATA('WAIT 30 SECONDS FOR OPINPUT'); 

/* Wait up to 30 seconds for operator input */ 
CNMGETDATA FUNC(FLUSHQ) QUEUE(OPERQ) ; 

/* Remove the operator input from the queue */ 
CNMCOMMAND DATA('WAIT CONTINUE'); 

/* Continue waiting for more operator input */ 

A wait continue command will satisfy the previous valid wait command. In the fol- 
lowing example, the command procedure will continue to wait using the wait cri- 
teria from the initial wait command because the second wait command is invalid. If 
the initial wait command is satisfied after 3 seconds, the command procedure will 
continue to wait for messages for the remaining 7 seconds (since the wait 20 
seconds for dataa was invalid). 
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CNMCOMMAND DATA('TRAP MESSAGES *'); 

/* Trap all messages */ 

CNMCOMMAND DATA('WAIT 10 SECONDS FOR MESSAGES'); 

/* Wait up to 10 seconds for the first trapped message */ 
CNMGETDATA FUNC(FLUSHQ) QUEUE(TRAPQ); 

/* Remove messages from the message queue */ 

CNMCOMMAND DATA('WAIT 20 SECONDS FOR DATAA'); 

/* Invalid wait for data (misspelled data) */ 

CNMGETDATA FUNC(FLUSHQ) QUEUE (DATAQ); 

/* Remove data from the data queue */ 

CNMCOMMAND DATA( 'WAIT CONTINUE' ) ; 

/* Continue waiting for the next trapped message */ 

Note: cnmgetd must complete successfully (hlbrc = o) before a wait continue will 
process correctly. 
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Return Codes: 



CNM_BAD_INVOCATION 


4 


wait was NOT issued from 
an hll or rexx command 
procedure. 


CNM_TOO_MANY 


8 


Too many operands. 


CNM_BAD_SYNTAX 


12 


Syntax error. 


CNM_BAD_COMMAND 


144 


wait was NOT issued from 
a command procedure 
running under an ost or 

NNT. 


CNM_NO_TRAP 


152 


wait issued but trap was 
not issued. Must issue 
valid trap before issuing 
wait for messages. 


CNM_NO_PREV_WAIT 


248 


No previous wait; wait con- 
tinue invalid. 



The following return codes are issued when a wait is satisfied. They are generated 
in place of a zero return code to inform the operator which event satisfied the wait. 



CNM_TIME_OUT_WAIT 


224 


wait timed out. 


CNM_GO_ON_WAIT 


228 


go satisfied wait. 


CNM_MSG_ON_WAIT 


232 


Message received during 

WAIT. 


CNM_OPINPUT_ON_WAIT 


236 


opinput received during 

WAIT. 


CNM_DATAJDN_WAIT 


240 


data received during wait. 
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HLL Service Routine Reference 

The following service routines may be invoked from a command processor or user 
exit routine written in pl/i or c. A description of each service routine is given, along 
with its associated parameters, usage notes, and return codes. 

When writing a command processor or user exit routine in pl/i, the user may invoke 
an hll servrce routine using the call or macro format. The pl/i macro format has 
been provided for those users that wish to code only the required parameters for a 
particular hll service routine invocation. The user must code all of the parameters 
when using the pl/i call format or c invocation. 

When invoking a service routine from an hll command processor or user exit 
routine written in c, the first letter of the service routine name must be capitalized 
and the remaining letters must be lowercase. This restriction is a result of c being 
case-sensitive, pl/i does not have this restriction. 

CNMALTD (CNMALTDATA) - Alter Data On A Queue 

cnmaltd enables the user to alter the contents of the top message on the initial 
data queue. Lines may be inserted, replaced or deleted. 



PL/1 CALL FORMAT: 

CALL CNMALTD(hlbptr,adfunc,adbuf,adorigin t adqueue,adindex) 

PL/I MACRO FORMAT: 

CNMALTDATA FUNC(ao7t/nc) DAT A(adbuf) ORIGIN(ador/gm) 
QUEVE(adqueue) UHE(adlndex) 

C INVOCATION: 

void Cnmaltd(char *adfunc, void *adbuf, void *adorigin, int adqueue, 
ml adindex) 



Where: 

hlbptr 

A four byte pointer field containing the address of the hlb control block. 

adfunc 

An eight byte character field which specifies the function to be performed. 
Required for all cnmaltd calls. 

INSLINE Insert a new line in the message in the specified queue. 

adindex specifies the line number that the new line will 
have after it has been inserted. The index value may be 
one greater than the number of lines currently in the 
message in order to add a line on the end. All parameters 
are required for this function. 

REPLINE Replace a line of the current message in the specified 

queue (if it exists). All parameters are required for this 
function. 
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DELLINE Delete a line of the current message in the specified 

queue. The line specified by adindex (the index value) is 
physically removed from the queue. It is possible to delete 
all lines of a message. If the line that was last returned 
from getline orGETMSG is deleted, the message pointer is 
moved back to the line preceding the deleted line. (See 
"CNMGETD (CNMGETDATA) - Data Queue Manipulation" 
on page 206). adqueue and adindex are required parame- 
ters for delline. adorigin and adbuf are NOT required 
parameters for this function. 

adbuf 

A varying length character field containing the buffer to be inserted. Required 
with insline and repline but not used with delline. 

adorigin 

A character field of fixed length n (where n > = 38) to contain an origin block. 
The user must define an origin block {adorigin) to be passed as a parameter to 
cnmaltd. This must be a separate structure from the origin block (origblck) 
that was passed to the hll command processor or user exit routine as an initial 
parameter. orig_block_length cannot be less than 38. Refer to dsiporig 
(Appendix A) or dsicorig (Appendix C) for the pl/i and c mappings of an origin 
block. The user is responsible for updating the origin block (adorigin) to reflect 
changes made by cnmaltd. Required for insline and repline. Not required for 
delline. 

adqueue 

A four byte integer field containing the number (index) of the queue on which 
the operation is to be performed. The only queue allowed for cnmaltd is the 
initial data queue (idataq). The full message which invoked the hll command 
processor through message automation or the message which drove dsiexo2A 
is on the initial data queue. Required for all functions. 

adindex 

A four byte integer field containing the number of the line of the message at the 
head of the queue to be manipulated. Required for all functions. 

Usage Notes: 

cnmaltd was primarily designed for use in dsiexo2a where it enables the user to 
alter messages before they are automated or displayed. 

Reference "CNMSMSG (CNMSENDMSG) - Send Message or Command" on 
page 234 for the definitions of line types. 
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Return codes: 



CNMJ300D 





Everything OK. 


CNM_NO_STORAGE 


24 


Non-zero return code from 
dsiget macro. 


CNM_BAD_FUNC 


52 


Invalid adfunc value. 


CNM_BAD_QUEUE 


72 


Invalid adqueue value. 


CNM_BADJNDEX 


76 


Invalid adindex value. 


CNM_QUEUE_EMPTY 


80 


The specified queue is 
empty. 


CNM_BAD_ORIGBLOCK 


84 


Invalid value in 

ORIG_BLOCK_LENGTH. 


CNM_BAD_LENGTH 


88 


The length of {adbuf) is 
greater than ( > ) 32729. 


CNM_NOT_MLWTO 


92 


Message is not a multi-line 
message. 


CNM_BAD_LINETYPE 


96 


Invalid line type. Must be 
C,D,E,L,F, or ' '. 
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CNMCELL (CNMSTRCELL) - Storage Cell 

cnmcell can be used to allocate and free storage cells from a previously allocated 
storage pool. The token obtained by cnmpool must first be passed to cnmcell to 
identify the storage pool. 



PL/I CALL FORMAT: 

CALL CN MGELL{hlbptr,pcfunc,pctoken,pcstrptr) 

PL/I MACRO FORMAT. 

CNMSTRCELL FUNC(pcfync) TOKEN (pctok en) STRPTR(pcsfrpfr) 

C INVOCATION: 

void Cnmcell(char *pcfunc, int pctoken, void *pcstrptr) 



Where: 

hlbptr 

A four byte pointer field containing the address of the hlb control block. 

pcfunc 

An eight byte character field which specifies the function to be performed. 

ALLOC Allocate cell 

FREE Free cell 

pctoken 

A four byte integer field containing the token identifying the storage pool. Pro- 
vided by caller for all functions (token returned from cnmpool). 

pcstrptr 

A four byte pointer field to contain the address of the cell. Returned to caller 
for alloc, provided by caller for free. 

Usage Notes: 

A storage cell within a pool is associated with the NetView subtask under which it 
was allocated. It cannot be referenced from a task other than the one with which it 
is associated. 
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Return codes: 



CNM_GOOD 





Everything OK. 


CNM_NO_STORAGE 


24 


Non-zero return code from 
dsiget macro. 


CNM_BAD_TOKEN 


32 


Invalid pctoken. 


CNM_BAD_FUNC 


52 


Invalid pcfunc. 


CNM_BAD_CLASS 


112 


Possible storage overlay. 
Report to IBM service. 


CNM_BAD_ADDR 


160 


The storage pointed to by 
pcstrptr is not addressable. 


CNM_NOT_IN_POOL 


204 


Cell not in storage pool. 


CNM_BAD_CELL_ADDRESS 


256 


Address is not on valid cell 
boundary. 


CNM_CELL_ALREADY_FREE 


260 


Cell has already been 
freed. 
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CNMCMD (CNMCOMMAND) - Execute NetView Commands 

cnmcmd enables the user to execute a NetView command from an hll command 
processor. If the called command is a long running command, then the caller is 
suspended until the long running command has completed. The caller regains 
control at the instruction following the cnmcmd invocation. 



PL/I CALL FORMAT. 

CALL CHMCMQ{hlbptr,cmdstr) 

PL/I MACRO FORMAT: 

CNMCOMMAND DATA(crodsfr) 

C INVOCATION: 

void Cnmcmd(void *cmdstr) 



Where: 



hlbptr 

A four byte pointer field containing the address of the hlb control block. 

cmdstr 

A varying length character field containing the NetView command (including its 
parameters) to be executed. 

Usage Notes: 

Commands are invoked with a hdrmtype of hdrtypec. This is consistent with the 
NetView command list language and rexx. 

The return code from hll command processors and NetView long running com- 
mands will be returned properly to hll command processors through the cnmcmd 
interface. If you wish to call a long-running command and allow it to be separately 
rollable, you can prefix the command with cmd high. For example, cnmcommand 
data('cmd high browse netloga') would allow the browse screen to roll independ- 
ently from the calling hll command processor. See NetView Operation for more 
information on the cmd command. 

cnmcmd will not process immediate commands (type = i in dsicmd). If an hll 
command processor issues cnmcmd and the command to be executed is an imme- 
diate command, the command will fail with a return code of -3108. Refer to 
Example 2 in the Composite Return Code section of this chapter for an explanation 
of this return code. 

A negative return code generated from cnmcmd indicates a failure in the cnmcmd 
service routine. Refer to the following list of return codes for further explanation. 
A positive return code generated from cnmcmd indicates a failure in the NetView 
command that was to be executed by cnmcmd. Refer to the return codes listed for 
the NetView command in NetView Operation. A (-5) return code generated from 
cnmcmd indicates that the NetView command currently executing was cancelled. In 
this case, it is recommended that the command processor do any necessary 
cleanup and exit setting of hlbrc to -5 to pass the reset information to its caller. 
Refer to the "RESET Command" on page 180. 
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A (-1) return code generated from cnmcmd indicates an unexpected error in the 
called command procedure. 

cnmcmd cannot be invoked from an hll user exit routine. 

cnmcmd cannot be invoked from an hll command processor while holding a lock. 

The NetView Service Point Command Service (spcs) commands are not supported 
under the hll api and must not be invoked by cnmcmd. See NetView Customization: 
Writing Command Lists for more information on spcs commands. 
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Return codes: 



CNM_GOOD 





Everything OK. 


- CNM_BAD_INVOCATION 


-4 


Not invoked from a 
command processor. 


-CNM_NO_STORAGE 


-24 


Non-zero return code from 
dsiget macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsiget 
macro). 


-CNM_BAD_LENGTH 


-88 


Command length is invalid. 


-CNM_LOCKED 


-208 


cnmcmd issued while 
holding a lock. 


X-CNM_BAD_EXCMS 


X-3000 


Non-zero return code X. 
See values for X below. 


Z 




Return code from executed 
command. See usage 
notes for return codes (-5) 
and(-1). 



Values for X: 
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-4 


Non-zero return code, 4 
(drop), from user exit. 




-100-Y 


Non-zero retun code, Y, 
from dsices macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsices 
macro). 




-200-Y 


Non-zero return code, Y, 
from dsilcs (CWB) macro. 
(See NetView 
Customization: Using 
Assembler for more infor- 
mation on the dsilcs 
macro). 




-300-Y 


Non-zero return code, Y, 
from dsiget macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsiget 
macro). 




-400-Y 


From either dsiget or dsilcs 
indicates storage failure. 
The user exit is not 
invoked. (See NetView 
Customization: Using 
Assembler for more infor- 
mation on the dsiget or 
dsilcs macro). 




-500-Y 


Non-zero return code, Y, 
from either dsiget or dsilcs 
indicates storage failure. 
The user exit is not 
invoked. (See NetView 
Customization: Using 
Assembler for more infor- 
mation on the dsiget or 
dsilcs macro). 




-600-Y 


Non-zero return code, Y, 
from dsilcs (SWB) macro. 
(See NetView 
Customization: Using 
Assembler for more infor- 
mation on the dsilcs 
macro). 
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CNMCNMI (CNMI) - CNMI Access Under a DST 

NetView's cnmi service enables hll command processors (running under a dst with 
cnmi capability) to send and receive data across the cnmi. This service can be used 
in conjunction with cnmgetd to manipulate data on the cnmi solicited data queue 

(CNMIQ). 



i PL/1 CALL FORMAT: 

! CALL CNMCt4M\(hlbptr,cnfunc,cndata,cndest,cntimout) 

I PL/I MACRO FORMAT: 

I CNMI FUNC(cnfunc) DATA(cndafa) DEST(cndesf) TIMEOUT(c/tf/mouf) 

\ C INVOCATION: 

j void Cnmcnmi(char *cnfunc, void *cndata, char *cndest, int cntimout) 

t...... • .. ■ , ...... • ... .... 

Where: 

hlbptr 

A four byte pointer field containing the address of the hlb control block. 

cnfunc 

An eight byte character field which specifies the function to be performed. 
Required for all cnmcnmi calls. 

SENDRESP 

Send RU and expect only positive or negative response. 

SENDRPLY 

Send RU and expect reply RU or negative response. 

cndata 

A varying length character field containing the RU to be sent (beginning with 
an rh header). Required for all functions, ru length must be at least 3 bytes 
and no longer than 32,729 characters. 

cndest 

An eight byte character field which specifies the pu name. Required for all 
functions. 

cntimout 

A four byte integer field specifying the number of seconds to wait for 
reply/response. This is an optional parameter. If cntimout is not specified, the 
default is 0. If a timeout is specified, the rh header must indicate that the 
embedded ns ru solicits a reply. This will cause NetView to generate a prid. 
(See VTAM Programming). For requests that generate multiple ru (chained) 
replies, cntimout only applies to the first ru in the chain. 

Usage Notes: 

cnmcnmi cannot be invoked from an hll command processor while holding a lock. 

hll command processors enter a wait state when sending requests over the cnmi. 
The wait ends when a response or reply is received or when the specified timeout 
expires. 

cnmcnmi cannot be issued from an hll user exit routine. 
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Responses to cnmi solicited data requests will be placed on the cnmi solicited data 
queue (cnmiq). 

The xitci user exit routine will be invoked for both solicited and unsolicited data. 
Refer to Chapter 2 for more information on this exit. Also refer to Chapter 3 for a 
discussion on Unsolicited hll Data Services Command Processors (dscp). It is 
important to note that when the Unsolicited hll dscp receives control, the command 
buffer (cmdbuf) will contain the unsolicited data ru. 

For more information on installing a dst, refer to Chapter 3 on page 21 in this 
manual. 

Return Codes: 



CNM_GOOD 





Everything OK. 


CNM_BAD_INVOCATION 


4 


Not invoked from a 
command processor or not 
under a dst. 


CNM_NO_STORAGE 


24 


Non-zero return code from 
dsiget macro. 


CNM_BAD_RULENG 


48 


Invalid cndata length. 


CNM_BAD_FUNC 


52 


Invalid cnfunc. 


CNM_BADJTIMEOUT 


56 


cntimout less than (<) 0. 


CNM_NEED_PRID 


60 


Timeout specified but prid 
not generated. The prid 
generation bit in the ru 
must be set if a timeout is 
specified. 


CNM_NEG_RESPONSE 


64 


Negative response 
received. (Sense code in 

HLBSENSE). 


CNM_TIME_OUT 


68 


Timeout occured. 


CNM_LOCKED 


208 


cnmi issued while holding a 
lock. 


CNM_DST_FAILURE + X 


2000 + X 


Non-zero return code, X, 
which is the dsrb minor 
return code for solicited 
cnmi data. See NetView 
Customization: Using 
Assembler. 


CNM_BAD_ZCSMS + (X * 
100) + Y 


20000 + (X * 
100) + Y 


Non-zero return code 
(major), X, and non-zero 
return code (minor), Y, from 

DSIZCSMS. 
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CNMCPYS (CNMCOPYSTR) - Copy Storage 

cnmcpys enables the user to copy storage from one address to another address. 
This service routine allows the copy operation to process without ABENDing if the 
source or destination is not addressable. However, the service routine will not 
protect you from overwriting storage if it is addressable. 



PL/I CALL FORMAT: 

CALL CNMCPYS (hlbptr, csfrom, csto, cslen, cstype) 

PL/I MACRO FORMAT: 

CNMCOPYSTR FROM(csfrom) TO(csfo) LENG(cs/en) COPYTYPE(csfype) 

C INVOCATION: 

void Cnmcpys(void *csfrom, void *csto, int cslen, char *cstype) 



Where: 

hlbptr 

A four byte pointer field containing the address of the hlb control block. 

csfrom 

A four byte pointer field containing the address of the source data. 

csto 

A four byte pointer field to contain the address of the destination. 

cslen 

A four byte integer field containing the number of bytes of storage to be copied. 
Length = to 16777215. 

If the value specified by cslen is greater than the actual length of the specified 
csto buffer, a storage overlay could occur. Special care should be taken when 
deciding the value of cslen. 

cstype 

The type of copy to perform. Valid types follow: 

FIXTOFIX Copy cslen bytes of storage from a fixed length buffer to 

another fixed length buffer. 

FIXTOVAR Copy cslen bytes of storage from a fixed length buffer to a 

varying length buffer. 

VARTOFIX Copy cslen bytes of storage from a varying length buffer to 

a fixed length buffer. 

VARTOVAR Copy cslen bytes of storage from a varying length buffer to 

another varying length buffer. 

Usage Notes: 

The length field of varying length buffers will not be set or altered by cnmcpys. 

When using cnmcpys with c and when copying fixtofix, fixtovar orvARTOFix, you 
must pass cnmcpys a pointer to a pointer to your fixed length buffer. This can be 
done by designating a variable as a pointer to a string, and then passing cnmcpys 
the address of that pointer. 
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Return codes: 



CNM_GOOD 





Everything OK. 


CNM_BADJ_ENGTH 


88 


cslen greater than ( > ) 
16777215 or less than (<) 
0. Copy not performed. 


CNM_BAD_ADDR 


160 


The storage pointed to by 
csto is not addressable. 


CNM_BAD_CSTYPE 


252 


Invalid cstype. 


CNM_BAD_ESTAE 


15000 


Non-zero return code from 
estae macro. Refer to MVS 
Extended Architecture 
Supervisor Services and 
Macro Instructions for more 
detail. 
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CNMGETA (CNMGETATTR) - Query Message Attributes 

cnmgeta can be used to obtain attributes of messages on the initial data queue 
(idataq). Values of attributes are returned to the user in character string form. 



\ PL/I CALL FORMAT: 

I CALL CNMGETA{hlbptr,ganame,gadata,gadaUen,gaqueue) 

PL/I MACRO FORMAT: 

I CNMGETATTR ITEM{ganame) DATA(gacfafa) LEHG{gadatlen) QUEUE(gaqueue) 

l C INVOCATION: 

\ void Cnmgeta(char *ganame, void "gadata, int gadatlen, int gaqueue) 



Where: 

hlbptr 

A four byte pointer field containing the address of the hlb control block. 

ganame 

An eight byte character field which specifies the attribute. Following is a list of 
valid attributes: 



AREAID 



DESC 



JOBNAME 



JOBNUM 



MCSFLAG 



MSGTYP 



REPLYID 



ROUTCDE 



SESSID 



SMSGID 



SYSCONID 



Equivalent to &areaid which provides a one-letter (A-Z) 
identifier for the area on the console screen that displays 
the message. 

Equivalent to &desc which provides the system descriptor 
codes in a binary series of on (1) and off (0) characters, 
representing the descriptor code bits in order. 

Equivalent to &jobname which provides the 1 to 8 character 
mvs job name. 

Equivalent to &jobnum which provides the 8 character mvs 
job number. 

Equivalent to &mcsflag which provides the system 
message flags in a binary series of on (1) and off (0) codes. 

Equivalent to &msgtyp which provides the system message 
type as three consecutive binary characters. 

Equivalent to &replyid which provides a three character 
reply identifier for wtor command replies. 

Equivalent to &routcde which provides the system routing 
codes in a binary series of on (1) and off (0) characters, 
representing the routing code bits in order. 

Equivalent to &sessid which is the taf session id where the 
message originated. 

Equivalent to &smsgid which provides an 8 character value 
that identifies a particular instance of a message. 

Equivalent to &sysconid which provides the console 
number (in decimal) that receives the message. 
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SYSID Equivalent to &sysid which provides the identifier of the mvs 

system that sent the message. 

gadata 

A varying length character field to contain the resulting value for the specified 
attribute. 

gadatlen 

A four byte integer field containing the length of gadata. This is the maximum 
length of the area provided to receive the returned data, gadatlen is provided 
by the user. 

If the value specified by gadatlen is less than the length of the data to be 
returned, the truncated data will be returned in gadata and a return code of 
cnm_data_trunc will be generated. The full length of the data that was trun- 
cated is stored in hlbleng [Hlbleng). 

If the value specified by gadatlen is equal to or greater than the length of the 
data to be returned, and hlbrc {Hlbrc) = cnm_good, the length of the returned 
data will be stored in hlbleng {Hlbleng). 

If the value specified by gadatlen is greater than the length of the receiving 
data buffer (gadata), a storage overlay could occur. Special care should be 
taken when deciding the value of gadatlen. 

gaqueue 

A four byte integer field containing the number of the queue holding the 
message. Only attributes for the initial data queue (idataq) are useful at this 
time. 

Usage Notes: 

The following NetView command list language variables are available in either the 
message buffer or the origin block. They are not accessible through cnmgeta. 

&HDRMTYPE Provides the 1 character NetView message type of the 

message and is equivalent to orig_msg_type. 

&LINETYPE Provides the multi-line write-to-operator (mlwto) line type 

and is equivalent to orig_line_type. 

&MSGID Is the message identifier of the message most recently 

received by NetView and is equivalent to orig_process. 

&MSGORIGIN Is the domain where the message most recently received 

by NetView orginated and is equivalent to origjdomain. 

&MSGSTR Is the message text of the message most recently 

received by NetView and is equivalent to the message 
string itself. 

Note: Refer to NetView Customization: Writing Command Lists for further 
description of the NetView command list language variables. 

Some of the attributes apply to all types of messages, while others apply to only 
certain types of messages. For example, jobname is only meaningful for messages 
received from mvs via the subsystem interface. 
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Return codes: 



CNM_GOOD 





Everything OK. 


CNM_DATA_JRUNC 


40 


gadatlen was too small. 
Data truncated. 


CNM_BAD_FUNC 


52 


Invalid ganame. 


CNM_BAD_QUEUE 


72 


Invalid gaqueue value. 


CNM_QUEUE_EMPTY 


80 


The specified queue is 
empty. 


CNM_BAD_LENGTH 


88 


gadatlen less than (<) 0. 


CNM_BAD_ADDR 


160 


The storage pointed to by 
gadata is not addressable. 
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CNMGETD (CNMGETDATA) - Data Queue Manipulation 

cnmgetd can be used to manipulate input queues that may consist of single and 
multi-line messages. 



^W^M;W$ffi : $ 



PUt CALL FORMAT: 

GALLCMMGE7D(hlbptr,gdfuncsdbuf,gdbuflen,gdorigin t g(iqueue,gctindex) 

PL/I MACRO FORMAT: 

CNMGETDATA FUMC(gdfunc) DATA(gdbuf) LEMG(gdbuflen) ORIGIN(gcfor/g/n) 
QUEUE(gcfqoeue) UNE(gdmdex) 

C INVOCATION 

void Cnmgetd(char *gdfunc, void *gdbuf, int gdbuflen, void *gdorigin, 
int gdqueue, int gdindex) 



Where. 

hlbptr 

A four byte pointer field containing the address of the hlb control block. 

gdfunc 

An eight byte character field which specifies the function to be performed. 

GETMSG 

Returns the first line of the next message in the specified queue. If one or 
more lines of a multi-line message has already been returned by getline or 
getmsg, the current getmsg skips to the next message in the queue, dis- 
carding any skipped lines. 

GETLINE 

Returns the next line in the specified queue. This will cross message 
boundaries until the queue is empty. The user must check orig_line_type 
to determine which line is last. 

PEEKLINE 

Returns a line from the message at the head of the specified queue whose 
line number is specified by gdindex. Flushed and gotten lines can be 
peeked unless the message was flushed or a line in a subsequent 
message was gotten. 

FLUSHLIN 

Skips over the next line of the specified queue. This will cross message 
boundaries until the queue is empty. 

FLUSHMSG 

Skips to the next message in the specified queue. 

FLUSHQ 

Discards all messages in the specified queue. 

gdbuf 

A varying length character field containing the buffer to be returned for getmsg, 
getline, and peekline. Required for getline, getmsg, peekline. Not required for 

FLUSHLIN, FLUSHMSG, FLUSHQ. 
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gdbuflen 

A four byte integer field containing the length of gdbuf. This is the maximum 
length of the area provided to receive the returned message, gdbuflen is pro- 
vided by the user. Required for getmsg. getline, peekline. Not required for 

FLUSHLIN, FLUSHMSG, FLUSHQ. 

If the value specified by gdbuflen is less than the length of the message to be 
returned, the truncated message will be returned in gdbuf and a return code of 
cnm_data_trunc will be generated. The full length of the message that was 
truncated is stored in hlbleng (Hlbleng). 

Note: get requests continue to advance the cursor independent of the trun- 
cation. A combination of peekline and flushlin|flushmsg|flushq should be 
used when retrieving complete lines of unknown length. 

If the value specified by gdbuflen is equal to or greater than the length of the 
message to be returned, and hlbrc {Hlbrc) — cnm_good, the length of the 
returned message will be stored in hlbleng {Hlbleng). 

If the value specified by gdbuflen is greater than the length of the receiving 
data buffer (gdbuf), a storage overlay could occur. Special care should be 
taken when deciding the value of gdbuflen. 

gdorigin 

A character field of fixed length n (where n > = 38) to contain an origin block. 
The user must define an origin block {gdorigin) to be passed as a parameter to 
cnmgetd. This must be a separate structure from the origin block (origblck) 
that was passed to the hll command processor or user exit routine as an initial 
parameter. orig_block_length cannot be less than 38. Refer to dsiporig 
(Appendix A) and dsicorig (Appendix C) for the pl/i and c mappings of an origin 
block. Required for getline, getmsg, peekline. Not required for flushlin, 

FLUSHMSG, FLUSHQ. 

gdqueue 

A four byte integer field containing the number (index) of the queue on which to 
perform the operation. Required for all functions. Following is a list of valid 
values: 



TRAPQ 
OPERQ 

DATAQ 

IDATAQ 

CNMIQ 



Queue 1 Message queue. Contains trapped messages. 

Refer to "TRAP Command" on page 183. 

Queue 2 Operator input queue. Refer to "GO 

Command" and "QUEUE Command" on 
page 179. 

Queue 3 Data queue. Contains data sent from another 

hll command processor or user exit routine. 
Refer to "CNMSMSG (CNMSENDMSG) - Send 
Message or Command" on page 234. 

Queue 4 Initial data queue. Contains the full message 

which invoked the hll command processor 
through message automation or the message 
which drove dsiexo2A. 

Queue 5 cnmi solicited data queue. Contains ru's solic- 

ited via the cnmi service routine. Chained ru's 
are treated like multi-line messages. Refer to 
"CNMCNMI (CNMI) - CNMI Access Under a 
DST" on page 199. 
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gdlndex 

A four byte integer field containing the number (index) of the line of the 
message at the head of the queue to be manipulated. Required only for 

PEEKLINE. 

Return codes: 



CNM_GOOD 





Everything OK. 


CNM_DATA_TRUNC 


40 


gdbuflen was too small. 
Data truncated. 


CNM_BAD_FUNC 


52 


Invalid gdfunc value. 


CNM_BAD_QUEUE 


72 


Invalid gdqueue value. 


CNM_BADJNDEX 


76 


Invalid gdindex value. 


CNM_QUEUE_EMPTY 


80 


The specified queue is 
empty. 


CNM_BAD_LENGTH 


88 


gdbuflen less than (<) 0. 


CNM_BAD_ADDR 


160 


The storage pointed to by 
either gdbuf or gdorigin is 
not addressable. 
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CNMINFC (CNMINFOC) - Query NetView Character Information 



cnminfc allows you to obtain information about the current NetView environment. 
cnminfc returns character data. 



PL/I CALL FORMAT: 

CALL CNMINFC (hlbptr,icname,icdata,icdatlen) 

\ PL/1 MACRO FORMAT: 
CNMINFOC ITEM(/cname) DfiJA(icdata) LENG(/cdaf/en) 

C INVOCATION: 

\ void Cnminfc(char *icname, void *icdata, int icdatlen) 



Where: 

hlbptr 

A four byte pointer field containing the address of the hlb control block. 

icname 

An eight byte character field which specifies the name of a variable. Following 
is a list of allowable names: 

APPLID Equivalent to &applid which is the NetView domain id 

appended with a 3-character alphanumeric value assigned 
by NetView. 

CLOCK Current value returned by stck instruction (not display- 

able). 

DATE Equivalent to &date which is the current date in the format 

mm/dd/yy. 

DATETIME Equivalent to &date followed by &time. 

DOMAIN Domain id. 

HCOPY Equivalent to &hcopy which is the name of the hardcopy 

log task started by the operator. 

LU Equivalent to &lu which is the logical unit name for the 

operator terminal. 

NVVER NetView version and release. 

OPID Equivalent to &opid which is the id of the operator issuing 

the call to cnminfc. 

OPSYSTEM Equivalent to &opsystem which is a character string that 

indicates the operating system under which the hll 
command processor or user exit routine is running. 

PID Process id for this hll command processor or user exit 

routine. Used for cnmsmsg with smmsgtyp-DATA (not dis- 
piayable). 

STARTIME NetView start time (not displayable). 
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TASK Equivalent to &task (ost|nnt|Ppt|mnt|dst|opt|hct) which is 

the 3-character string depending on the task under which 
the hll command processor or user exit routine is running. 

TASKNAME Name of the task under which the hll command processor 

or user exit routine is running. 

TIME Equivalent to &time which is the cpu time in the format 

hh:mm. 

VTAM vtam level. 

Icdata 

A varying length character field to contain the character data to be returned. 

icdatlen 

A four byte integer field containing the length of icdata. This is the maximum 
length of the area provided to receive the returned data, icdatlen must be 
greater than zero and less than 32729 and is provided by the user. 

If the value specified by icdatlen is less than the length of the data to be 
returned, the truncated data will be returned in icdata and a return code of 
cnm_data_trunc will be generated. The full length of the data that was trun- 
cated is stored in hlbleng {Hlbleng). 

If the value specified by icdatlen is equal to or greater than the length of the 
data to be returned, and hlbrc {Hlbrc) = cnm_good, the length of the returned 
data will be stored in hlbleng {Hlbleng). 

If the value specified by icdatlen is greater than the length of the receiving data 
buffer (icdata), a storage overlay could occur. Special care should be taken 
when deciding the value of icdatlen. 

Usage Notes: 

Refer to NetView Customization: Writing Command Lists for a description of the 
NetView command list language variables. 

clock, pid, and startime are eight character representations of the TOD-clock (time- 
of-day) value returned by the stck instruction. 

Return codes: 



CNM_GOOD 





Everything OK. 


CNM_DATA_TRUNC 


40 


icdatlen was too small. 
Data truncated. 


CNM_BAD_FUNC 


52 


Invalid icname. Value 
unchanged. 


CNM_BAD_LENGTH 


88 


icdatlen less than (<) 0. 


CNM_BAD_ADDR 


160 


The storage pointed to be 
icdata is not addressable. 
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CNMINFI (CNMINFOI) - Query NetView Integer Information 

cnminfi enables the user to obtain information about the current NetView environ- 
ment, cnminfi returns integer data. 



PL/I CALL FORMAT: 

| CALL CNMlNFl{h(bptr,iiname,iinumb) 

J ' 
PL/1 MACRO FORMAT: 

[■CNMINFOI ITEM(/7/?ame) DAlA(iinumb) 

I 

rC INVOCATION: 

I void Cnminfi(char *iiname, int Vinumb) 



Where: 

hlbptr 

A four byte pointer field containing the address of the hlb control block. 

iiname 

An eight byte character field which specifies the name of the variable. Fol- 
lowing is a list of allowable names: 

ABENDRTN* 

If processing as a long running command abend routine, then return true. 
From dsitvb NetView control block (tvbabend). This field is a product- 
sensitive programming interface. 

ATTENDED* 

If there is an operator associated with this task, then return true. An 
autotask is attended if it has been assigned to a console using the 
autotask command. 

AWAITINP* 

If waiting for operator input, then return true. From dsitvb NetView control 
block. 

CLOSING* 

If NetView is terminating, then return true. From dsimvt NetView control 
block (mvtclose). This field is a product-sensitive programming interface. 

COLORS 

Number of colors that can be displayed. 

LOGOFRTN* 

If processing as a long running command logoff routine, then return true. 
From dsitvb NetView control block (tvblogof). This field is a product- 
sensitive programming interface. 

MVTUFLD 

User field. From dsimvt NetView control block (mvtufld). This field is a 
product-sensitive programming interface. 

OPER3270* 

If ost with a 327x display terminal attached, then return true. 
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RESETREQ* 

If reset or cancel was requested, then return true. From dsitvb NetView 
control block (tvbreset). tvbreset will be turned off as a result of this 
query. This field is a product-sensitive programming interface. Refer to 
"RESET Command" on page 180 for further detail. 

SCRNSER 

Return serial number of the screen update. From dsitib NetView control 
block (tibscrsn). This field is a product-sensitive programming interface. 

USEREXIT 

If the integer value is 0, the environment is that of a command processor. 

If the integer value is 2 through 15, the environment is that of a user exit. 

If the integer value is one of the following, the environment is that of a user 
exit running under a dst. Following is a list of values of the user exits 
running under a dst. 

userdint 233 dsm Initialization Exit 

uservint 234 vsam Initialization Exit 

uservinp 235 vsam Input Exit 

USERVOUT 236 VSAM Output Exit 

usercinp 237 cnmi Input Exit 

usercout 238 cnmi Output Exit 

userxlog 240 External Log Exit 

userbint 241 Sequential Log Initialization Exit 

userbout 242 Sequential Log Output Exit 

Refer to dsipcons (Appendix A) or dsiccons (Appendix C) for a list of con- 
stants useful when coding user exit routines. 



Note: The iinames followed by an (*) contain Boolean values. 
1 =True. 

iinumb 

A four byte integer field to contain the integer value returned. 

Return codes: 



False and 



CNM_GOOD 





Everything OK. 


CNM_BAD_FUNC 


52 


Invalid iiname. Value 
unchanged. 


CNM_BAD_ADDR 


160 


The storage pointed to by 
iinumb is not addressable. 
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CNMKIO (CNMKEYIO) - Keyed File Access Under a DST 

cnmkio provides access to dst managed key-sequenced vsam files from an hll 
command processor. This service routine will only perform its function when 
invoked from an hll command processor running under a dst task. Calls from 
other environments will be rejected. 



J PL/I CALL FORMAT: 

I CALL CttMK\0(hlbptr,vsfunc,vsdata,vsdatlen,vskey,vsoption) 

I PL/I MACRO FORMAT: 

I CNMKEYIO FUHC(vsfunc) DAT A(vsdata) LENG(vsdaf/en) KEY(vskey) 

I OPTIONS( vsoption) 

[ C INVOCATION: 

l void Cnmkio(char *vsfunc, void *vsdata, int vsdatlen, void *vskey, 

i char * vsoption) 



Where: 

hlbptr 

A four byte pointer field containing the address of the hlb control block. 

vsfunc 

An eight byte character field which specifies the function to performed. 

GETJEQ Get record equal to key. 

Note: The key field must match exactly, including blanks. 

GET_EH Get record equal to or higher than key. 

GET_NEXT Get next record in ascending sequence. 

GETJPREV * Get next record in descending sequence. 

PUT Write/rewrite record. 

ERASE Erase record. 

ENDREQ Cancel a request for update. 

vsdata 

A varying length character field to contain the buffer to be returned/written. 
Provided by the user for put, returned for get, and is not required for erase or 

ENDREQ. 

vsdatlen 

A four byte integer field containing the length of vsdata. This is the maximum 
length of the area provided to receive the returned data, vsdatlen is provided 
by the user. Required only for get. 

If the value specified by vsdatlen is less than the length of the data to be 
returned, the truncated data will be returned in vsdata and a return code of 
cnm_data_trunc will be generated. The full length of the data that was trun- 
cated is stored in hlbleng (Hlbleng). 

If the value specified by vsdatlen is equal to or greater than the length of the 
data to be returned, and hlbrc (Hlbrc) = cnm_good, the length of the returned 
data will be stored in hlbleng (Hlbleng). 



Chapter 12. Command and Service Reference 213 



If the value specified by vsdatlen is greater than the length of the receiving 
data buffer {vsdata), a storage overlay could occur. Special care should be 
taken when deciding the value of vsdatlen. 

vskey 

A varying length character field containing the vsam key used for access to the 
requested data. Required for get_eq, get_eh or erase/direct. Not required for 

GET_NEXT, GET_PREV, PUT, ERASE/UPDATE, Or ENDREQ. 

vsoption 

An eight byte character field that specifies the type of access to the file. Pro- 
vided by user for all functions except endreq. 

UPDATE Get record for update or replace. Erase record that was 

gotten for update, put/update and erase/update must be 
preceded by a successful get/update, update can only be 
used with get, put, and erase. 

NOUPDATE Record will not be updated, noupdate can only be used 

with get. 

DIRECT Put a new record directly to the file or erase a record 

directly from the file (without invoking get first), put/direct 
can only be used for a new record. If the record already 
exists, cnm_dupl_key will be returned. For an existing 
record, erase/direct gives the same result as get/update 
followed by erase/update. If the record does not exist, 
cnm_not_found will be returned, direct can only be used 
with put and erase. 

Usage Notes: 

cnmkio cannot be issued from an hll user exit routine. 

cnmkio cannot be invoked from an hll command processor while holding a lock. 

For more information on vsam files, refer to VSAM Programming. 

For more information on installing a dst, refer to Chapter 3 on page 21 of this 
manual. 
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Return codes: 



CNM_GOOD 





Everything OK. 


CNM_BAD_IN VOCATION 


4 


Not invoked from a 
command processor. 


CNM_NOT_FOUND 


20 


Record with requested 
vskey not found. 


CNM_NO_STORAGE 


24 


Non-zero return code from 
dsiget macro. 


CNM_END_FILE 


36 


End of file encountered. 


CNM_DATA_TRUNC 


40 


vsdatlen was too small. 
Data truncated. 


CNM_BAD_FUNC 


52 


Invalid vsfunc. 


CNM_BAD_LENGTH 


88 


vsdatlen less than ( < ) 0. 


CNM_BAD_OPTION 


128 


Invalid vsoption. 


CNM_BAD_ADDR 


160 


The storage pointed to by 
vsdata is not addressable. 


CNM_BAD_COMBO 


176 


invalid combination vsfunc 
and vsoption. 


CNM_DUPL_KEY 


200 


Record with requested key 
already exists. Existing 
record is not changed. 


CNMJ.OCKED 


208 


cnmkio issued while 
holding a lock. 


(CNM_BAD_ZVSMS + X) * 
256 + Y 


(100 + X) * 256 
+ Y 


Non-zero return code from 
dsizvsms. X is the major 
return code from dsizvsms. 
Y is the minor return code 
from dsizvsms. 


CNM_DST_FAILURE + X 


2000 + X 


Non-zero return code, X, 
which is the dsrb minor 
return code for solicited 
cnmi data. See NetView 
Customization: Using 
Assembler. 
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CNMLK (CNMLOCK) - Control A Lock 

cnmlk can be used to obtain, release, and test the control of a named lock. This 
service can be used to serialize access to resources shared by multiple tasks. 
cnmlk does not allow for serialization within a task, hll command processors 
holding a lock may not use any services that can cause execution of an hll 
command processor to be suspended. 



PL/l CALL FORMAT: 

CALLCHMLK(hlbptr,lkfunc,lkname,lkscope,lkoption) 

PUI MACRO FORMAT: 

CNMLOCK FUNC(//cfunc) NAME(//cname) SCOPE(tfcscope) OPTION(/fropf/on) 

C INVOCATION. 

void Cnmlk(char *lkfunc, void *lkname, char *lkscope, char *lkoption) 



Where: 

hlbptr 

A four byte pointer field containing the hlb control block. 

Ikfunc 

An eight byte character field which specifies the function to be performed. 

UNLOCK Release control of lock name. 

LOCK Obtain control of lock name. 

TEST Test if lock name is available. 

Ikname 

A varying length character field to hold the user-defined name of lock. (Length 
is 1-12 characters). Required for all functions. 

Ikscope 

An eight byte character field. This field is reserved for future use. The user 
should provide a null or blank value for all functions. 

Ikoption 

An eight byte character field which specifies if the hll command processor or 
user exit routine should wait for the lock to become available. Required only 
for LOCK. 

WAIT Wait until the lock is available. The task will be sus- 

pended. 

NOWAIT Do not wait if lock is not available. An appropriate return 

code will be issued (cnm_locked orCNM_LOCK_iNUSE). 

Usage Notes: 

It is not recommended to invoke cnmsmsg with smdestyp = oper while holding a 
lock. There is a possibility that the operator task may be running with autowrap off 
and the hll command processor or user exit routine might hang waiting for the 
operator to clear the screen, thus holding the lock for an indefinite period of time. 
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A hierarchical order on lock requests is used to prevent deadlock. The alphabet- 
ical order of the lock names defines the hierarchy. For example, assume the last 
lock request was for Ikname = gvariable. A new lock request for Ikname = 
tvariable will be successful since tv ari able is alphabetically greater than 
gvariable. However, a new lock request for Ikname = cvariable will be unsuc- 
cessful since cvariable is alphabetically less than gvariable. Return code 
cnm_locked will be generated and the lock request will fail. 

Return codes: 



CNM_GOOD 





Everything OK. 


CNM_NO_STORAGE 


24 


Non-zero return code from 
dsiget macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsiget 
macro). 


CNM_BAD_FUNC 


52 


Invalid Ikfunc. 


CNM_BAD_NAME 


108 


Length of Ikname greater 
than ( > ) 12 or the specified 
Ikname was not LOCKed. 


CNM_BAD_OPTION 


128 


Invalid Ikoption. 


CNMJ.OCKED 


208 


A previous request for 
control of Ikname has been 
made for the same task. 
The task has control of the 
specified Ikname. 


CNM_LOCKJNUSE 


212 


Ikname is not available; 
currently held by another 
task. 


CNM_BAD_ENQ + X 


21000 + X 


Non-zero return code X 
from dsienq macro. See 
MVS Extended Architecture 
Supervisor Services and 
Macro Instructions for 
values for X. 
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CNMMEMO (CNMOPENMEM) - Open NetView Partitioned Data Set 

cnmmemo enables the user to open members of NetView partitioned data sets. A 
token identifying the open member is returned to the user. This token is passed to 
cnmmemr to read records from the member and to cnmmemc to close the member. 



PL/I CALL FORMAT: 

CALL CHMhAEMO(htbptr,motoken,moddname,momemnam) 

PUl MACRO FORMAT: 

CNMOPENMEM TOKEN(moto*en) DATASFHmodcfoame) 
MEMBER(momemnam) 

C INVOCATION: 

void Cnmmemo(int *motoken, char *moddname, char *momemnam) 



Where: 

hlbptr 

A four byte pointer field containing the address of the hlb control block. 

motoken 

A four byte integer field to contain the token to be used by subsequent 
cnmmemr and cnmmemc requests. 

moddname 

An eight byte character field which specifies the dd name of the partitioned 
data set. The NetView predefined partitioned data sets are: 

BNJMISC 

BNJPNL1 

BNJPNL2 

CNMPNL1 

DSICLD 

DSIMSG 

DSIPARM 

DSIPRF 

DSIVTAM 

momemnam 

An eight byte character field which specifies the name of the member. 

Return codes: 
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CNM_GOOD 





Everything OK. 


CNM_BAD_DDNAME 


16 


Invalid moddname (not 
found). 


CNM_NOT_FOUND 


20 


momemnam not found. 


CNM_NO_STORAGE 


24 


Non-zero return code from 
dsiget macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsiget 
macro). 


CNM_BAD_ADDR 


160 


The storage pointed to by 
motoken is not address- 
able. 


CNM_BAD_DKS + X 


10000 + X 


Non-zero return code, X, 
from dsidks macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsidks 
macro). 
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CNMMEMR (CNMREADMEM) - Read NetView Partitioned Data Set 

cnmmemr allows you to read a record from a member of a NetView partitioned data 
set that was previously opened by cnmmemo. The token returned by cnmmemo must 
be passed to cnmmemr to allow the read. 



PL/I CALL FORMAT: 

CALLCHMMEMR(hlbptr,mrtoken,mrdata,mrdatlen) 

PL/I MACRO FORMAT: 

CNMREADMEM TOKEN(mrto*en) DATA(mrdata) LENG {mrdatlen) 

C INVOCATION: 

void Cnmmemr(int mrtoken, void *mrdata, int mrdatlen) 



Where: 

hlbptr 

A four byte pointer field containing the address of the hlb control block. 

mrtoken 

A four byte integer field containing the token returned by cnmmemo. 

mrdata 

A varying length character field to contain the received record. 

mrdatlen 

A four byte integer field containing the length of mrdata. This is the maximum 
length of the area provided to receive the returned record, mrdatlen is pro- 
vided by the user. 

If the value specified by mrdatlen is less than the length of the record to be 
returned, the truncated record will be returned in mrdata and a return code of 
cnm_data_trunc will be generated. The full length of the record that was trun- 
cated is stored in hlbleng (Hlbleng). 

If the value specified by mrdatlen is equal to or greater than the length of the 
record to be returned, and hlbrc (Hlbrc) = cnm_good, the length of the 
returned record will be stored in hlbleng {Hlbleng). 

If the value specified by mrdatlen is greater than the length of the receiving 
data buffer (mrdata), a storage overlay could occur. Special care should be 
taken when deciding the value of mrdatlen. 
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Return codes: 



CNM_GOOD 





Everything OK. 


CNMJOERROR 


28 


I/O error occurred. 


CNM_BAD_TOKEN 


32 


Token not found. 


CNM_END_FILE 


36 


End of file encountered. 


CNM_DATA_TRUNC 


40 


mrdatlen was too small. 
Data truncated. 


CNM_BAD_LENGTH 


88 


mrdatlen less than (<) 0. 


CNM_BAD_ADDR 


160 


The storage pointed to by 
mrdata is not addressable. 


CNM_BAD_DKS + X 


10000 + X 


Non-zero return code, X, 
from dsidks macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsidks 
macro). 
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CNMMEMC (CNMCLOSMEM) - Close NetView Partitioned Data Set 

cnmmemc enables the user to close a member of a NetView partitioned data set 
that was previously opened by cnmmemo. The token returned by cnmmemo must be 
passed to cnmmemc to allow the close. All members opened by cnmmemo will auto- 
matically be closed at program termination. 



PllliflilSillltlSi 



PUI CALL FORMAT: 

CALL CHMMEMC{hlbptr,mctoken) 

PUI MACRO FORMAT: 

CNMCLOSMEM TOKEN(mcfofren) 

C INVOCATION: 

void Cnmmemc(int mctoken) 



Where: 



Mm^&mmim l M 



hlbptr 

A four byte pointer field containing the address of the hlb control block. 

mctoken 

A four byte integer field containing the token returned by cnmmemo. 

Return codes: 



CNM_GOOD 





Everything OK. 


CNM_BAD_TOKEN 


32 


Token not found. 


CNM_BAD_DKS + X 


10000 + X 


Non-zero return code, X, 
from dsidks macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsidks 
macro). 
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CNMNAMS (CNMNAMESTR) - Named Storage 

cnmnams allows the user to allocate, free, locate, and reallocate named areas of 
virtual storage. 

PL/i CALL FORMAT: 

CALL CNM N AMS(hlbptr f n8func,nsptr,nsname,nsleng,nsclass) 

PL/I MACRO FORMAT. 

I CNMNAMESTR FUNC(nsfunc) STRPTR(/?sp*r) NAMEfasname} LENG(/?s/e/?si) 
I CLASS (nsclass) 

C INVOCATION: 

| void Cnmnams(char *nsfunc, void *nsptr t void *nsname, int *nsleng, 

Where: 

hlbptr 

A four byte pointer field containing the address of the hlb control block. 

nsfunc 

An eight byte character field which specifies the function to be performed: 

ALLOC Allocate named storage area. 

FREE Free/deallocate named storage area. 

LOCATE Locate existing named storage area. 

REALLOC Reallocate named storage area. Old data is preserved. 

nsptr 

A four byte pointer field containing the address of the named storage. 
Returned to caller for alloc, realloc, and locate. Not required for free. 

nsname 

A varying length character field to contain the name of the storage area. 
Required for all functions (provided by the caller). 

nsleng 

A four byte integer field containing the size of the named storage area. 
Required by caller for alloc and realloc. Returned to caller for locate. Not 
required for free. 

nsclass 

A four byte integer field containing the class of the named storage area. 
Required by caller for alloc and realloc. Not required for free or locate. 

— residency of caller 

1 - 31 bit storage 

2 = 24 bit storage 

Usage Notes: 

Named storage areas provide a way of sharing data among different hll command 
processors and user exit routines or among multiple invocations of a hll command 
processor or user exit routine. Once allocated, a named storage area remains 
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allocated until it is either explicitly freed or the task under which it was allocated 
terminates. 

A named storage area is associated with the NetView subtask under which it was 
allocated. Named storage areas can only be manipulated (locate, free, reallocate) 
by hll command processors and user exit routines running under the mainline of 
that task. You cannot reference a named storage area from a task other than the 
one with which it is associated. 

If alloc is requested for a name that has already been allocated, the address of the 
existing area is returned along with a non-zero return code. 

If a previously allocated named storage area is reallocated to be larger than the 
original area, the content of the original area is preserved. If a previously allo- 
cated named storage area is reallocated to be smaller than the original area, the 
content of the original area is preserved up to the length specified by the nsleng 
parameter. 

Return codes: 
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CNM_GOOD 





Everything OK. 


CNM_NOT_FOUND 


20 


REALLOC, FREE, or 
LOCATE requested but no 
previous ALLOC was done. 


CNM_NO_STORAGE 


24 


Non-zero return code from 
dsiget macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsiget 
macro). 


CNM_BAD_FUNC 


52 


Invalid function. 


CNM_BAD_LENGTH 


88 


nsleng less than ( < ) 0. 


CNM_DUPL_NAME 


104 


nsname already allocated. 
Allocation not done. 


CNM_BAD_NAME 


108 


Length of nsname greater 
than(>)12. 


CNM_BAD_CLASS 


112 


Invalid nsclass. 


CNM_BAD_ADDR 


160 


The storage pointed to by 
nsname or nsleng is not 
addressable. 


CNM_BAD_PUSH + X 


4000 + X 


Non-zero return code, X, 
from dsipush macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsipush 
macro). 


CNM_BAD_POP + X 


5000 + X 


Non-zero return code, X, 
from dsipop macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsipop 
macro). 
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CNMPOOL (CNMSTRPOOL) - Storage Pool 

cnmpool can be used to allocate, free, and locate storage pools. A storage pool is 
composed of one primary and zero or more secondary blocks of storage. Each 
block of storage consists of a specified number of cells (of equal size) which can be 
allocated/freed using cnmcell. Storage pool services provide a way to effectively 
manage large numbers of fixed size storage elements. 



PL/I CALL FORMAT: 

CALL CHMPOOL{hlbptr,spfunc,sptoken,spname,spleng,sppricnt t 
spseccnt,spclass) 

PL/I MACRO FORMAT: 

CNMSTRPOOL FUNC(spfunc) TOKEN(sptofcen) NAME(spname) LENG(spteng) 
PRICELLS {sppricnt) SECCELLS(spseccnf) CLASS(spc/ass) 

C INVOCATION: 

void Cnmpool(char *spfunc, int *sptoken, void *spname, int spleng, 
int sppricnt, int spseccnt, int spclass) 



Where: 

hlbptr 

A four byte pointer field containing the address of the hlb control block. 

spfunc 

An eight byte character field which specifies the function to be performed. 



ALLOC 


Allocate pool 


FREE 


Free pool 


LOCATE 


Locate pool 



sptoken 

A four byte integer field to contain the token identifying the storage pool. 
Returned for alloc and locate for use with cnmcell service. Not required for 

FREE. 

spname 

A varying length character field containing the name of the storage pool. 
Required for all functions and provided by the caller. 

spleng 

A four byte integer field containing the size of each cell in the pool. Required 
for alloc. Not required for free or locate. 

sppricnt 

A four byte integer field containing the number of cells in the primary block. 
Required only for alloc. 

spseccnt 

A four byte integer field containing the number of cells in the secondary block. 
Required only for alloc. 

spclass 

A four byte integer field containing the storage class of the pool. Required for 
alloc Not required for free or locate. 
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= residency of caller 

1 - 31 bit addressable 

2 - 24 bit addressable 

Usage Notes: 

A storage cell within a pool is associated with the NetView subtask under which it 
was allocated. It cannot be referenced from a task other than the one with which it 
is associated. 

All storage pool names must be unique within a given task. 
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Return codes: 



CNM_GOOD 





Everything OK. 


CNM_NOT_FOUND 


20 


spname not found. 


CNM_NO_STORAGE 


24 


Non-zero return code from 
dsiget macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsiget 
macro). 


CNM_BAD_FUNC 


52 


Invalid spfunc. 


CNM_BAD_LENGTH 


88 


spleng less than ( < ) 4. 


CNM_DUPL_NAME 


104 


spname already allocated. 
Allocation not done. 


CNM_BAD_NAME 


108 


Length of spname greater 
than(>)12. 


CNM_BAD_CLASS 


112 


Invalid spclass. 


CNM_BAD_ADDR 


160 


The storage pointed to by 
sptoken is not addressable. 


CNM_BAD_PRI_COUNT 


192 


Invalid sppricnt. 


CNM_BAD_SEC_COUNT 


196 


Invalid spseccnt. 
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CNMSCAN (CNMSSCAN) - Parse and Convert a Character String— (PL/I) 

cnmscan can be used to extract data from an input string and assign the extracted 
data to one or more receiving variables. The input string is scanned from left to 
right and is interpreted according to the specifications defined by the format string. 
Each of the receiving variables must have the same data type as its corresponding 
type specifier in the format string. The user can specify up to ten receiving vari- 
ables in the argument list. The number of fields successfully parsed and converted 
is returned to the user in panumfld. 

When the first format specification is found, the value of the first input field is con- 
verted according to the first format specification and stored in the first receiving 
variable in the argument list. When the second format specification is found, the 
value of the second input field is converted according to the second format specifi- 
cation and stored in the second receiving variable in the argument list. This con- 
tinues until all of the format specifications in the format string have been 
processed. 



PL/I CALL FORMAT: 

CALL CUMSCAH{hlbptr,pastring,pattern,panumfld,pafield1,...,pafield10) 

PL/I MACRO FORMAT: 

CNMSSCAN DATAipastring) FORMAT(pattern) COUHJipanumfld) 
P1 {pafield1),...,PWipafield10) 



Where: 

hlbptr 

A four byte pointer field containing the address of the hlb control block. 

pastring 

A varying length character field containing the input string to be parsed and 
converted. 

pattern 

A varying length character field containing the format specifications. The 
format string {pattern) determines how the data elements in the input string 
(pastring) will be parsed and converted. 

panumfld 

A four byte integer field to contain the number of fields successfully parsed and 
converted. This field is returned to the user. 

pafield1,...,pafield10 

List of receiving variables. The last variable named in this list will receive the 
value of the last input field parsed and converted according to the last specifi- 
cation in the format string. Each of the variables named in this list must be 
declared to have the same data type as its corresponding type specifier in the 
format string. The user can specify up to ten variables to receive parsed and 
converted data. 

Usage Notes: 

The format string consists of a series of format specifications which are defined as 
follows: 
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• The character % that designates the beginning of each format specification. 
(Required for each format specification). 

• The character * that indicates the data in the input string for this format specifi- 
cation should be read from the input string but not assigned to a receiving vari- 
able. (Optional) 

• A numerical value that defines a maximum field width to scan in the input 
string. (Optional) 

• The character h (halfword) or I (long or full-word) that indicates the size of the 
argument that the value of the parsed or converted input data will be assigned. 
(Optional) 

• Any number of white space characters can be interspersed within or between 
format specifications for readability. However, blanks should not be inserted 
between { } unless this is the desired effect. (Optional) 

• The type specifier that specifies the data type of the parsed or converted input 
data to be stored in the receiving variable. (Required) 

The type specifier directs the conversion of the next input field, cnmscan places the 
result in the receiving variable, unless assignment suppression was specified with 
an *. An input field is a string of characters other than spaces, unless the type 
specifier is a c or {}. The input field extends to the next character that doesn't 
meet the criteria of the type specifier or until the width of the field, if specified, is 
reached. 

The type specifier determines the interpretation of the next input field. If the input 
field does not meet this expectation, cnmscan returns to its caller. The following 
type specifiers are valid: 

c Expect any character. Space characters that are ordinarily skipped are 

read. Specify a field width to parse and convert more than one character. 
For example, %3c will retrieve the next three characters of the input string. 
To skip over spaces before obtaining a character, use %1s. Refer to the dis- 
cussion below on the type specifier s. 

Note: The receiving variable to contain the character string result must be 
declared as a fixed length character string. 

d Expect decimal value. Input is an optionally signed sequence of decimal 
digits. Any spaces in the input string preceding the decimal digits will be 
skipped. The decimal digits are delimited by the next non-decimal character 
in the input string. 

n A data element is not parsed and converted from the input string. The value 
stored is the number of characters successfully read (including blanks) from 
the input string up to that point in the call to cnmscan. 

Note: If the end of the input string occurs before the %n has been reached, 
the value stored will be zero. 

s Expect a character string. Any spaces in the input string preceding the 

character string will be skipped. The character string is delimited by a 
space. If a field width is not specified, the field width will default to the 
length of the string. 

Note: The receiving variable to contain the character string result must be 
declared as a varying length character string. 
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u Expect an unsigned decimal value. Any spaces in the input string preceding 
the decimal digits will be skipped. The decimal digits are delimited by the 
next non-decimal character in the input string. 

x Expect a hexadecimal value. Input is an optionally signed sequence of 

hexadecimal digits. Any spaces in the input string preceding the 
hexadecimal digits will be skipped. The hexidecimal digits are delimited by 
the next non-hexadecimal character in the input string. 

{} Expect a string that is not delimited by spaces. Follow the { with a set of 

characters followed by a }. The corresponding input field is read to the first 
character that does NOT appear between {}. If the first character is a -. (or 
'5f'x), the effect is reversed; the input field is read to the first character that 
appears between {}. 

{-1} parse until the end of the string. 

{-■a} parse until the character 'a' is found. 

{a} parse until any character other than an 'a' is found. 

{} parse until any character is found. 

Note: The receiving variable to contain the character string result must be 
declared as a varying length character string. 

If your format string specifies more data elements to be parsed and converted than 
your input string contains, the results are unpredictable. 

If your format string specifies fewer data elements to be parsed and converted than 
your input string contains, the remaining data elements in the input string are 
ignored. 

cnmscan returns when it encounters a format specification it does not expect or 
when it reaches the end of the input string. 

If cnmscan is invoked using the pl/i call format and all ten pafields are not speci- 
fied, a warning message will be issued at compile time. 

cnmscan can only be used in an hll command processor or user exit routine 
written in pl/i. 

The parsel2R command provides a function similar to cnmscan and remains avail- 
able for use. However, because of its conversion capabilities, cnmscan is more 
suitable to hll command processors. 

Return Codes: 



CNM_GOOD 





Everything OK. 


CNM_BAD_ADDR 


160 


The storage pointed to by 
panumfld or 

pafield1,...,pafield10 is not 
addressable. 
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CNMSCOP (CNMSCOPECK) - Scope Check for Security 

cnmscop determines if the user is authorized to issue a specific 
command/keyword/value combination from a particular operator id. The scope 
check is based on the scope of authority of the operator id of the task executing 
cnmscop. Only NetView scope checking is performed. No attempt is made to 
determine if a resource is in the task (operator's) span of control. 



PL/I CALL FORMAT: 

CALL CHMSCOP{hlbptr,sccmd,sckwd,scvalue} 

PL/I MACRO FORMAT: 

CNMSCOPECK VERB(sccmd) KEYWORD(sertwof) VALUE(scva/ue) 

C INVOCATION: 

void Cnmscop(char *sccmd, char *sckwd, char *scvalue) 



Where: 

hlbptr 

A four byte pointer field containing the address of the hlb control block. 

sccmd 

An eight byte character field which specifies the verb of the command to be 
scope checked. Blanks or (*) imply that the command verb that invoked the hll 
command processor will be used. 

sckwd 

An eight byte character field which specifies the keyword of the command to 
scope check. Blanks or (*) imply that no specific keyword is checked. 

scvalue 

An eight byte character field which specifies the value of sckwd to be scope 
checked. Blanks or (*) imply that no specific keyword value is to be checked. 

Usage Notes: 

If cnmscop is issued from an hll user exit routine, sccmd must be specified. Other- 
wise, return code cnm_bad_command will be generated. 

Scope of commands, keywords, and keyword values is defined in dsicmd. Operator 
class is defined in each operator's profile. For further information see NetView: 
Installation and Administration Guide. 

cnmscop will not check the validity of a command. It should only be used to verify 
if an operator has authorization to issue a particular command. 
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Return codes: 



CNMJ300D 





Everything OK. 


CNM_NO_STORAGE 


24 


Non-zero return code from 
dsiget macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsiget 
macro). 


CNM_COMMAND_NA 


132 


sccmd not authorized. 


CNM_KEYWORD_NA 


136 


sckwd not authorized. 


CNM_VALUE_NA 


140 


scvalue not authorized. 


CNM_BAD_COMMAND 


144 


Invalid syntax of sccmd or 
sccmd was not found. 
Check for length greater 
than (>) 8 or invalid char- 
acters in sccmd. sccmd 
may be incorrectly defined 
in dsicmd. See usage notes 
if cnmscop was invoked 
from an hll user exit 
routine. 


CNM_BAD_KEYWORD 


148 


value (scvalue) was speci- 
fied without a keyword 
(sckwd). sckwd must be 
specified when scvalue is 
specified. 


CNM_BAD_CES + X 


9000 + X 


Non-zero return code, X 
from dsices macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsices 
macro). 


CNM_BAD_KVS + X 


11000 + X 


Non-zero return code, X 
from dsikvs macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsikvs 
macro). 



Chapter 12. Command and Service Reference 233 



CNMSMSG (CNMSENDMSG) - Send Message or Command 

cnmsmsg enables the user to send a message or command to specific destinations 
in your network. 



PL/I CALL FORMAT: 

CALL CHMSMSG(hlbptr f smtext,smmsgtyp,smdestyp,smdestid) 

PL/i MACRO FORMAT: 

CNMSENDMSG DATA(smtexf) MSGTYPE {smmsgtyp) DESTTYPE(sm<tesfyp) 
DEST(smdestid) 

C INVOCATION: 

void Cnmsmsg{void *smtext, char "smmsgtype, char *smdestyp, 
char *smdestid) 



Where: 

hlbptr 

A four byte pointer field containing the address of the hlb control block. 

smtext 

A varying length character field containing the message text. Required param- 
eter. 

• If smmsgtyp is msg, msg_c, msg_l, msg_d, msg_e, or msg_f then smtext is the 
text of the message. 

• If smmsgtyp is command then smtext is either a command procedure name 
or a NetView command. 

• If smmsgtyp is request then smtext is the name of the hll command 
processor that should send the data. 

• If smmsgtyp is data then the process id must be concatenated with the 
data, smtext must be specified as follows: 

smtext = ORIGIN->ORIG_PROCESS|rtext' 

smmsgtyp 

An eight byte character field which specifies the message type. Required 
parameter. Values are: 

MSG Single line message. ORIG_LINE_TYPE= ' '. 

MSG_C Control line message. ORIG_LINE_TYPE= 'C. 

MSG_L Label line message. ORIG_LINE_TYPE= 'L'. 

MSG_D Data line message. ORIG_LINE_TYPE= 'D'. 

MSG_E End of multi-line message. ORIG_LINE_TYPE= 'E'. 

MSG_F MSG_D and MSG_E combined. ORIG_LINE_TYPE= ' F' . 

COMMAND Command to be executed. 

Note: The command is asynchronously scheduled for exe- 
cution. 
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REQUEST Request for data. 

Note: request is similar to command except the command 
to execute is the name of the hll command processor that 
is to return data through cnmsmsg with smmsgtyp = data. 

DATA Non-printable data in response to REQUEST. 

Note: NetView places a process id in the origin block 
(origblck). This id must be included at the beginning of the 
returned data. This process id is used to route data to the 
correct instance of an hll command processor or user exit 
routine if there are multiple activations of the same hll 
command processor or user exit routine. The data 
returned from cnmsmsg with smmsgtyp = DATA can be 
read by cnmgetd from the data queue (dataq). 

smdestyp 

An eight byte character field which specifies the destination type. Required 
parameter. Values are: 



OPER 


Operator task invoking 


TASK 


Another task 


SYSOP 


System console 


NETVLOG 


NetView log 


EXTLOG 


External log (e.g. SMF) 


SEQLOG 


Sequential log 


AUTHRCV 


Authorized receiver 


OPCLASS 


All operators in group 



smdestid 

Destination id. Required when smdestyp is extlog, seqlog, task or opclass. 

When smdestyp is extlog, seqlog or task, smdestid is the name of the destina- 
tion task. An asterisk (*) may be used to imply 'self when smdestyp = task. 
Specifying smdestid = * is the same as issuing cnmsmsg with smdestyp = 
oper and smdestid = null. 

When smdestyp is opclass, smdestid is the group id of a particular group of 
operators defined by the assign command. Refer to the assign command in the 
NetView Operation manual for further detail. 

Note: ppt is accepted as a synonym for the ppt task (xxxxxppt) where xxxxx is 
the domain id in the local NetView. 

The following table shows message and destination type combinations which are 
not allowed: 
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Table 2. Invalid Message and Destination Type Combinations 





OPER 


TASK 


SYSOP 


NETVLOG 


EXTLOG 


SEQLOG 


AUTHRCV 


OPCLASS 


MSG 


MSG_C 






X 




X 


X 






MSG_L 






X 




X 


X 






MSG_D 






X 




X 


X 






MSG_E 






X 




X 


X 






MSG_F 






X 




X 


X 






COMMAND 


X 




X 


X 


X 


X 


X 


X 


REQUEST 


X 




X 


X 


X 


X 


X 


X 


DATA 


X 




X 


X 


X 


X 


X 


X 



Usage Notes: 

Approximately 32K of data may be sent by cnmsmsg. 

cnmsmsg will generate a return code of cnm_bad_invocation when invoked from 
dsiexo4 or dsiexo9. cnmsmsg can be invoked from dsiexo2a if smdestyp is task. All 
other invocations of cnmsmsg from dsiexo2A will generate a return code of 

CNM_BAD_INVOCATION. 

The excmd command queues a NetView command to another task where it is exe- 
cuted, cnmsmsg also allows the user to send a command to another task in a 
similar way by specifying smmsgtyp = command, smdestyp = task, and the desired 
smtext and smdestid. 

Messages sent to a console with smmsgtyp = msg_c, msg_d, msg_e, msg_f or msg_l 
will be truncated if they are longer than the screen width of that console. 

The user can display as many control (msg_c) and label (msg_l) lines on a console 
as desired. However, a maximum of six control or label lines will be held on the 
screen if the data lines for that multi-line message cause the screen to wrap. 

It is not recommended to invoke cnmsmsg with smdestyp = oper while holding a 
lock. There is a possibility that the operator task may be running with autowrap off 
and the hll command processor or user exit routine might hang waiting for the 
operator to clear the screen, thus holding the lock for an indefinite period of time. 
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Return codes: 



CNM_GOOD 





Everything OK. 


CNM_BAD_INVOCATION 


4 


Not invoked from an 
allowed user exit. 


CNM_NO_STORAGE 


24 


Non-zero return code from 
dsiget macro. (See 
NetView Customization: 
Using Assembler for more 
information on the dsiget 
macro). 


CNM_BAD_LENGTH 


88 


smtext is too long. 


CNM_BAD_MSGTYP 


116 


Invalid message type. 


CNM_BAD_DESTYPE 


120 


Invalid destination type. 


CNM_TYP_CONFLICT 


124 


Conflict between message 
and destination type. 


CNM_LOG_INACTIVE 


216 


WLS failure-log was inac- 
tive. 


CNM_TASK_INACTIVE 


220 


MQS failure-task was inac- 
tive. 


CNM_BAD_MQS + X 


1000 + X 


Bad return code, X, from 
dsimqs message queue 
macro. (See NetView 
Customization: Using 
Assembler for more infor- 
mation on the dsimqs 
macro). 


CNM_BAD_WLS + X 


6000 + X 


Bad return code, X, from 
dsiwls write to log macro. 
(See NetView 
Customization: Using 
Assembler for more infor- 
mation on the dsiwls 
macro). 


CNM_BAD_PSS + X 


7000 + X 


Bad return code, X, from 
dsipss presentation ser- 
vices macro. (See NetView 
Customization: Using 
Assembler for more infor- 
mation on the dsipss 
macro). 


CNM_BAD_WTO + X 


8000 + X 


Bad return code, X, from 
dsiwcs write to operator 
macro. (See NetView 
Customization: Using 
Assembler for more infor- 
mation on the dsiwcs 
macro). 
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CNMVARS (CNMVARPOOL) - Set or Retrieve Variables 

A variable pool is a collection of named variables whose values can be set or 
retrieved by NetView command procedures and hll user exit routines. The fol- 
lowing types of variable pools can be accessed from hll command processors or 
hll user exit routines: 

• The hll command processor or user exit routine's own pool. 

• The variable pool of the calling command procedure if the current hll 
command processor or user exit routine was called from a command proce- 
dure. 

• The task global pool shared by all command procedures and hll user exit rou- 
tines running under a NetView task. 

• The common global pool shared by all command procedures and hll user exit 
routines running in a NetView address space. 



PL/I CALL FORMAT: 

CALL GHMVAR$(hlbptr,cvfunc,cvdata,cvdatlen,cvname,cvpool) 

PL/I MACRO FORMAT: 

CNMVARPOOL FUNC(cvfunc) HMAE(cvname) POOL(cvpool) DATA(cvdafa) 
LENG(cvdatfen) 

C INVOCATION: 

void Cnmvars(char *cvtunc, void *cvdata, int cvdatlen, void *cvname, 
char *cvpool) 



1 



M^^^^Ss^k^^M 



Where: 

hlbptr 

A four byte pointer field containing the address of the hlb control block. 

cvfunc 

An eight byte character field which specifies the function to be performed. 
Required for all cnmvars calls. 

PUT Set variable value. 

GET Get variable value. 

DCL Declare local variable to belong to one of the global pools, or 

reset it to the local pool. (You cannot declare a variable to 
belong to the caller's pool). 

cvdata 

A varying length character field containing the value of the named variable. 
Required for put and get. Not used for dcl. 

cvdatlen 

A four byte integer field containing the length of cvdata. This is the maximum 
length of the area provided to receive the returned data, cvdatlen is provided 
by the user. Required only for get. 

If the value specified by cvdatlen is less than the length of the data to be 
returned, the truncated data will be returned in cvdata and a return code of 
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cnm_data_trunc will be generated. The full length of the data that was trun- 
cated is stored in hlbleng {Hlbleng). 

If the value specified by cvdatlen is equal to or greater than the length of the 
data to be returned, and hlbrc (Hlbrc) = cnm_good, the length of the returned 
data will be stored in hlbleng {Hlbleng). 

If the value specified by cvdatlen is greater than the length of the receiving 
data buffer (cvdata), a storage overlay could occur. Special care should be 
taken when deciding the value of cvdatlen. 

cvname 

A varying length character field which specifies the name of variable. 
Required for all functions. 

Valid characters are A-Z, 0-9, @, #, $, 0, ., !, ?, and underscore. The first char- 
acter of cvname must not be a number or a period. 

cvpool 

An eight byte character field which specifies the variable pool. Required for all 
functions. 

LOCAL The local pool of the current hll command processor or 

user exit routine. 

TGLOBAL Task global. 

CGLOBAL Common global. 

CALLER The local pool of the calling command procedure or hll 

user exit routine (if one exists). 

Usage Notes: 

The user has the ability to access all existing NetView command list language and 
rexx global variables (both task and common) using cnmvars. In the NetView 
command list language, all variable names (local and global) are restricted to a 
length of 1 to 11 characters. In rexx, local variable names can be 1 to 250 charac- 
ters while global variables must be 1 to 31 characters. In hll, all variable names 
(local and global) are restricted to a length of 1 to 31. 

If you are accessing rexx or hll global variables from the NetView command list 
language, the rexx and hll variable names must adhere to NetView command list 
language rules. The character set allowed for variable names in NetView 
command list language is also smaller than in rexx and hll. The valid characters 
for rexx variable names are the same as hll; refer to the parameter cvname 
above. 

You must have a calling NetView command list language, rexx, or hll command 
procedure before you can put or get to a caller pool. Otherwise, a return code of 
cnm_bad_pool will be issued. 

You do not have to initially put a value into the calling hll command processor or 
user exit routine's local pool before issuing a put in the called hll command 
processor or user exit routine's caller pool. When control is returned back to the 
calling hll command processor or user exit routine, a get can be issued for the 
same variable name in the local pool to retrieve the value set in the called hll 
command processor or user exit routine's caller pool. 
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Any put's in an hll command processor or user exit routine's caller pool will 
change the value of the same variable name in the calling command procedure or 
hll user exit routine's local pool. 

You can get three different values (cvdata) in the same variable name {cvname) if 
you specify different pools (cvpool). For example: 

CNMVARS FUNC('PUT') NAME(x) POOL ('LOCAL') DATA('cvdatal'); 
CNMVARS FUNC('PUT') NAME(x) POOL('CGLOBAL') DATA('cvdata2'); 
CNMVARS FUNC('PUT') NAME(x) POOL('TGGLOBAL') DATA('cvdata3'); 

The calling hll command processor or user exit routine's local pool is the same 
as the called hll command processor or user exit routine's caller pool. 

dcl can be useful when a hll command processor or user exit routine invokes view. 
The user must insure that the variables are properly declared to the corresponding 
common or task global pools. Otherwise, the variables used may be from the 
local pool and the view screen will not be automatically updated. 

Task and common global variables must be declared to their respective pools 
before invoking view from an hll command processor or user exit routine. Other- 
wise, view will not pick up the values. See the following examples: 

Example 1 : 

rexx or NetView command list language has declared variables to the task or 
common global pool and values have been assigned to these variables. These 
values need to be displayed on a view panel from an hll command processor or 
user exit routine. Before invoking view, the following MUST be coded in the hll 
command processor or user exit routine: 

CNMVARS FUNC('DCL') NAME(cvname) POOL('CGLOBAL') 
or CNMVARS FUNC('DCL') NAME (cvname) POOL('TGLOBAL'). 

Example 2: 

rexx or NetView command list language has declared variables to the task or 
common global pool and values have been assigned to these variables. These 
values need to be changed within an hll command processor or user exit routine 
and then displayed on a view panel. Before invoking view, the following MUST be 
coded in the hll command processor or user exit routine: 

CNMVARS FUNC('PUT') NAME(cvname) POOL('CGLOBAL') DATA(cvdata) 

CNMVARS FUNC('DCL') NAME(cvname) POOL('CGLOBAL') 
or 

CNMVARS FUNC('PUT') NAME (cvname) POOL('TGLOBAL') DATA (cvdata) 

CNMVARS FUNC('DCL') NAME (cvname) POOL('TGLOBAL') 

Note: The dcl may precede the put. 

Example 3: 

An hll command processor or user exit routine has set values for either task or 
common variables. Before invoking view, the following must be coded in the hll 
command processor or user exit routine: 

CNMVARS FUNC('DCL') NAME(cvname) POOL('CGLOBAL') 
or 

CNMVARS FUNC('DCL') NAME (cvname) POOL('TGLOBAL') 

rv .-+,,„,;-,„+;„„. | leinn PI I and C 



Note: If only a dcl is done (with no put), the view panel will be blank for that vari- 
able. 

Example 4: 

It may be necessary to declare (dcl) a variable back to the local pool. For 
example, assume you have the same variable name in both the local and common 
global pool. If you have just invoked view, the variable is declared to the common 
global pool. If you want to change the value of the variable in the local pool, issue 
the following: 

CNMVARS FUNC('DCL') NAME(cvname) POOL ('LOCAL') 
Return codes: 



CNM_GOOD 





Everything OK. 


CNM_NOT_FOUND 


20 


cvname not found. 


CNM_DATA_TRUNC 


40 


cvdatlen was too small. 
Data truncated. 


CNM_BAD_FUNC 


52 


Invalid cvfunc. 


CNM_BAD_LENGTH 


88 


cvdatlen less than (<) or 
cvdata greater than (>) 
255. 


CNM_BAD_NAME 


108 


Invalid cvname. 


CNM_BAD_POOL 


156 


Invalid cvpool. 


CNM_BAD_ADDR 


160 


The storage pointed to by 
cvdata is not addressable. 


CNM_BAD_CDS + X 


14000 + X 


Non-zero return code, X. 
See values for X below. 


Values for X: 




4 


Invalid variable name. 




8 


Variable name already 
defined in dictionary. 




12 


Insufficient storage. 




20 


Value length limit was 
exceeded. 




28 


No command procedure 
related to current action. 




32 


Data was truncated. 
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Appendix A. PL/I Control Blocks and Include Files 



DSIPLI 



This appendix describes the pl/i Control Blocks and Include files needed to write in 

PL/I. 



/* 7 

/* NAME = DSIPLI */ 

/* 7 

/* DESCRIPTIVE NAME = Main HLL PL/I Include File */ 

/* 7 

/* 5665-362 for MVS/XA */ 

/* 5664-204 for VM */ 

/* 5666-343 for VSE */ 

/* THIS PRODUCT CONTAINS */ 

/* "RESTRICTED MATERIAL OF IBM" */ 

/* (c) COPYRIGHT IBM CORP 1989 */ 

/* ALL RIGHTS RESERVED */ 

/* LICENSED MATERIALS-PROPERTY OF IBM */ 

/* REFER TO COPYRIGHT INSTRUCTION FORM */ 

/* NUMBER G120-2083 */ 

/* 7 

/* STATUS = NetView V1R3 */ 

/* 7 

/* FUNCTION = DSIPLI is required and must be included by all HLL */ 

/* programs written in PL/I. DSIPLI includes all of the */ 

/* external HLL control blocks and include files needed to run */ 

/* PL/I programs in the NetView environment. */ 

/* */ 

/* NOTES = see below */ 

/* */ 

/* DEPENDENCIES = none */ 

/* 7 

/* RESTRICTIONS = none */ 

/* 7 

/* REGISTER CONVENTIONS = not applicable */ 

/* 7 

/* PATCH LABEL = not applicable */ 

/* 7 

/* MODULE TYPE = include file */ 

/* 7 

/* PROCESSOR = PL/I */ 

/* 7 

/* EXTERNAL REFERENCES = none */ 

/* 7 

/* CHANGE ACTIVITY */ 

/* 7 

/********************************************************************/ 

%INCLUDE DSIPCONS; /* Constants */ 

%INCLUDE DSIPHLB; /* Mapping of HLB */ 

%INCLUDE DSIPORIG; /* Mapping of Origin block */ 

%INCLUDE DSIPHLLS; /* HLL service rtn. definitions */ 

%INCLUDE DSIPCNM; /* HLL return code constants */ 
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DSIPCONS 



/•••••it******************************************************** 

/* */ 

/* NAME = DSIPCONS */ 

/* V 

/* DESCRIPTIVE NAME = HLL PL/I Constants */ 

"/* V 

/* 5665-362 for MVS/XA */ 

/* THIS PRODUCT CONTAINS */ 

/* "RESTRICTED MATERIAL OF IBM" */ 

/* (c) COPYRIGHT IBM CORP 1989 */ 

/* ALL RIGHTS RESERVED */ 

/* LICENSED MATERIALS-PROPERTY OF IBM */ 

/* REFER TO COPYRIGHT INSTRUCTION FORM */ 

/*. NUMBER G120-2083 */ 

/* V 

/* STATUS = NetView Release 3 */ 

/* V 

/* FUNCTION - This file contains the definitions for constants */ 

/* that are helpful when coding HLL modules in PL/I. */ 

/* V 

/* NOTES = see below */ 

/* */ 

/* DEPENDENCIES = none */ 

/* */ 

/* RESTRICTIONS = none */ 

/* */ 

/* REGISTER CONVENTIONS = not applicable */ 

/* V 

/* PATCH LABEL = not applicable */ 

/* */ 

/* MODULE TYPE = constants */ 

/* V 

/* PROCESSOR = PL/I */ 

/* V 

/* EXTERNAL REFERENCES = none */ 

/* */ 

/* CHANGE ACTIVITY */ 

/* V 
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/••♦A****************************************************************/ 

/* Constants common across HLL services */ 

/********************************************************************/ 



DCL TRAPQ 
OPERQ 
DATAQ 
IDATAQ 
CNMIQ 



FIXED BIN(31,0) 
FIXED BIN(31,G) 
FIXED BIN(31,0) 
FIXED BIN(31,0) 
FIXED BIN(31,0) 



INIT(l), 
INIT(2), 
INIT(3), 
INIT(4), 
INIT(5); 



/******************************************************************** y 

/* Constants for calls to CNMALTD */ 

/********************************************************************] 

DCL INSLINE CHAR(8) INIT( ' INSLINE '), 
REPLINE CHAR(8) INIT( 'REPLINE '), 

DELLINE CHAR(8) INIT('DELLINE '); 

******************************************************************** i 



/ 

/* Constants for CNMCPYS 



•••••••A************************************************************] 



/ 

DCL FIXTOFIX CHAR(8) INIT('FIXTOFIX'), 

FIXTOVAR CHAR(8) INIT('FIXTOVAR'), 

VARTOFIX CHAR(8) INIT('VARTOFIX'), 

VARTOVAR CHAR(8) INIT('VARTOVAR'); 



********************************************************************] 



/ 

/* Constants for calls to CNMGETD 



******************************************************************** t 



I 

DCL GETMSG CHAR (8) 
GETLINE CHAR(8) 
PEEKLINE CHAR(8) 
FLUSHLIN CHAR(8) 
FLUSHMSG CHAR (8) 
FLUSHQ CHAR(8) 



INIT(' GETMSG 
INITCGETLINE 
INIT(' PEEKLINE 
INIT('FLUSHLIN 
INITC FLUSHMSG 
INIT(' FLUSHQ 






******************************************************************** i 



/ 

/* Constants for CNMCNMI 



********************************************************************, 



/ 

DCL SENDRESP CHAR(8) INIT('SENDRESP'), 
SENDRPLY CHAR(8) INIT('SENDRPLY') ; 



********************************************************************; 



/ 

/* Constants for CNMLK 



********************************************************************, 



/ 

DCL UNLOCK 
LOCK 
TEST 
WAIT 
NOWAIT 



CHAR(8) INITCUNLOCK 

CHAR(8) INIT(' LOCK 

CHAR(8) INITCTEST 

CHAR(8) INITCWAIT 

CHAR(8) INIT( 'NOWAIT 
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/********************************************************************, 

/* Constants for CNMNAMS, CNMPOOL and CNMCELL *y 

/********************************************************************< 



DCL ALLOC 


CHAR(8) INITC ALLOC '), 


FREE 


CHAR(8) INITC FREE '), 


LOCATE 


CHAR(8) INITC LOCATE '), 


REALLOC 


CHAR(8) INITC REALLOC '); 



DCL RESIDENT FIXED BIN(31,0) INIT(O), 
ST0RAG31 FIXED BIN(31,0) INIT(l), 
ST0RAG24 FIXED BIN(31,0) INIT(2); 

A********************************************************************/ 

/* Constants for CNMSMSG */ 

****************************************************************** 



/ 

dcl msg char(8) initc msg 
msg c char(8) initc msg c), 
msg^l char(8) init('msg~l'), 
msgj) char(8) initcmsgj) 1 ), 
msg_e char(8) init('msg e'), 
msg f char(8) init('msg~f') , 
command char(8) init('command 
request char(8) initc request 
data char(8) init('data 
oper char(8) init('oper 
task char(8) initc task 
sysop char(8) init('sysop 
netvlog char(8) initc netvlog 
extlog char(8) initc extlog 
seqlog char(8) initc seqlog 
authrcv char(8) initc authrcv 
opclass char(8) initc opclass 



'), 



********************************************************************. 



/ 

/* Constants for CNMVARS 

/ 



V 



******************************************************************** , 



DCL PUT 


CHAR(8) INITC PUT 




DCL 


CHAR(8) INITCDCL 




GET 


CHAR(8) INIT('GET 




LOCAL 


CHAR(8) INITC LOCAL 




TGLOBAL 


CHAR(8) INITC TGLOBAL 




CGLOBAL 


CHAR(8) INITC CGLOBAL 




CALLER 


CHAR(8) INITC CALLER 





/********************************************************************, 

/* Constants for CNMKIO *> 

/********************************************************************, 



DCL GET EQ CHAR (8) 


INITC GET EQ 




GET EH CHAR (8) 


INITCGET EH 




GET NEXT CHAR(8) 


INITC GET NEXT 




GET~PREV CHAR (8) 


INITCGET PREV 




ERASE CHAR (8) 


INITC ERASE 




ENDREQ CHAR (8) 


INITC ENDREQ 




UPDATE CHAR (8) 


INITC UPDATE 




NOUPDATE CHAR (8) 


INITC NOUPDATE 




DIRECT CHAR(8) 


INITC DIRECT 
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/•TIT************************************************************** 

/* Constants for user exits running under a DST */ 

/****************•************************************************ 



DCL USERASIS 


FIXED BIN(31,0) 


INIT(0), 


USERDROP 


FIXED BIN(31,0) 


INIT(4), 


USERSWAP 


FIXED BIN(31,0) 


INIT(8), 


USERLOG 


FIXED BIN(31,0) 


INIT(12), 


USERLOGR 


FIXED BIN(31,0) 


INIT(16), 


USERHCL 


FIXED BIN(31,0) 


INIT(20), 


USERHCLR 


FIXED BIN(31,0) 


INIT(24), 


USERDINT 


FIXED BIN(31,0) 


INIT(233), 


USERVINT 


FIXED BIN(31,0) 


INIT(234), 


USERVINP 


FIXED BIN(31,0) 


INIT(235), 


USERVOUT 


FIXED BIN(31,0) 


INIT(236), 


USERCINP 


FIXED BIN(31,0) 


INIT(237), 


USERCOUT 


FIXED BIN(31,0) 


INIT(238), 


USERXLOG 


FIXED BIN(31,0) 


INIT(240), 


USERBINT 


FIXED BIN(31,0) 


INIT(241), 


USERBOUT 


FIXED BIN(31,0) 


INIT(242); 
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DSIPHLB 



/* V 

/* NAME = DSIPHLB */ 

/* V 

/* DESCRIPTIVE NAME = HLL PL/I Mapping of DSIHLB */ 

/* V 

/* 5665-362 for MVS/XA */ 

/* THIS PRODUCT CONTAINS */ 

/* "RESTRICTED MATERIAL OF IBM" */ 

/* (c) COPYRIGHT IBM CORP 1989 */ 

/* ALL RIGHTS RESERVED */ 

/* LICENSED MATERIALS-PROPERTY OF IBM */ 

/* REFER TO COPYRIGHT INSTRUCTION FORM */ 

/* NUMBER G120-2083 */ 

/* 7 

/* STATUS = NetView Release 3 */ 

/* V 

/* FUNCTION = This files contains a PL/I mapping of DSIHLB, an */ 

/* internal control block. */ 

/* V 

/* NOTES = see below */ 

/* V 

/* DEPENDENCIES = none */ 

/* V 

/* RESTRICTIONS = none */ 

/* */ 

/* REGISTER CONVENTIONS = not applicable */ 

/* V 

/* PATCH LABEL = not applicable */ 

/* */ 

/* MODULE TYPE = structure map */ 

/* V 

/* PROCESSOR = PL/I */ 

/* V 

/* EXTERNAL REFERENCES = none */ 

/* V 

/* CHANGE ACTIVITY */ 

/* V 
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DCL 1 DSIHLB BASED (HLBPTR), 



3 HLBLEN 


FIXED BIN(31), 


/* 


3 HLBWKA 


PTR, 


/* 


3 HLBHLLS 


PTR, 


/* 


3 HLBTIB 


PTR, 


/* 


3 HLBUSER 


PTR, 


/* 


3 HLBRC 


FIXED BIN(31), 


/* 


3 HLBLENG 


FIXED BIN(31), 


/* 



3 HLBSENSE BIT(32), /* 
3 HLBRSRV BIT(32), /* 
3 HLBFFDCA CHAR (48); /* 



Length of HLB */ 
Pointer to WKA for API modules*/ 

Pointer to HLLS */ 

Pointer to TIB */ 

User Word */ 
Return code from last API call*/ 
Length of data returned if 
HLBRC = 0. Otherwise, length 
of data that would have been 
returned if truncation had 

not occurred. */ 

Sense code from CNMI */ 

Reserved */ 

First failure data capture */ 
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DSIPORIG 



/* V 

/* NAME = DSIPORIG */ 

/* V 

/* DESCRIPTIVE NAME = HLL PL/I Origin Block Mapping */ 

/* */ 

/* 5665-362 for MVS/XA */ 

/* THIS PRODUCT CONTAINS */ 

/* "RESTRICTED MATERIAL OF IBM" */ 

/* (c) COPYRIGHT IBM CORP 1989 */ 

/* ALL RIGHTS RESERVED */ 

/* LICENSED MATERIALS-PROPERTY OF IBM */ 

/* REFER TO COPYRIGHT INSTRUCTION FORM */ 

/* NUMBER G120-2083 */ 

/* V 

/* STATUS = NetView Release 3 */ 

/* V 

/* FUNCTION = This file defines the mapping of the origin block */ 

/* of the request that caused the execution of the procedure */ 

/* currently running. */ 

/* V 

/* NOTES = see below */ 

/* V 

/* DEPENDENCIES - none */ 

/* */ 

/* RESTRICTIONS - none */ 

/* */ 

/*■ REGISTER CONVENTIONS = not applicable */ 

/* V 

/* PATCH LABEL - not applicable */ 

/* V 

/* MODULE TYPE = structure map */ 

/* 7 

/* PROCESSOR = PL/I */ 

/* V 

/* EXTERNAL REFERENCES = none */ 

/* V 

/* CHANGE ACTIVITY */ 

/* V 



DCL 1 0RIG_BL0CK BASED, 

3 ORIG_BLOCK_LENGTH FIXED BINARY (31,0), 

3 0RIGJDUMMY1 CHAR(8), /* Reserved */ 

3 ORIG_DOMAIN CHAR(8), /* Origin domain ID */ 

3 ORIGJASK CHAR(8), /* Origin task ID */ 

3 ORIG PROCESS CHAR(8), 

3 ORIG"MSG_TYPE CHAR, /* Message type from HDRMTYPE */ 

3 0RIGJ.INE TYPE CHAR, /* Line type */ 

3 ORIG DUMMY2 CHAR(2); /* Reserved */ 
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DSIPHLLS 



/* */ 

/* NAME = DSIPHLLS */ 

/* V 

/* DESCRIPTIVE NAME = PL/I Definitions for HLL Service Routines */ 

/* */ 

/* 5665-362 for MVS/XA */ 

/* THIS PRODUCT CONTAINS */ 

/* "RESTRICTED MATERIAL OF IBM" */ 

/* (c) COPYRIGHT IBM CORP 1989 */ 

/* ALL RIGHTS RESERVED */ 

/* LICENSED MATERIALS-PROPERTY OF IBM */ 

/* REFER TO COPYRIGHT INSTRUCTION FORM */ 

/* NUMBER G120-2083 */ 

/* */ 

/* STATUS = NetView Release 3 */ 

/* */ 

/* FUNCTION = Define entry points for HLL service routines for */ 

/* PL/I. A macro definition is also provided for each HLL */ 

/* service routine. */ 

/* */ 

/* High-Level Language Service Routine Address Table */ 

/* */ 

/* This DSECT must correspond exactly to PART I of DSIHLLAR */ 

/* which contains the actual addresses of the service routines */ 

/* or, in XA, the address of a branch instruction that */ 

/* branches to a Linkage Assist Routine (LAR) that insures */ 

/* the service routine is called with AM0DE=31. */ 

/* V 

/* NOTES = see below */ 

/* V 

/* DEPENDENCIES = none */ 

/* V 

/* RESTRICTIONS = none */ 

/* */ 

/* REGISTER CONVENTIONS = not applicable */ 

/* V 

/* PATCH LABEL = not applicable */ 

/* * / 

/* MODULE TYPE = structure map */ 

/* */ 

/* PROCESSOR = PL/I */ 

/* */ 

/* EXTERNAL REFERENCES = none */ 

/* V 

/* CHANGE ACTIVITY */ 

/* */ 

/••••••••••••••A*****************************************************/ 
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DCL 1 DSIHLLS BASED (HLBHLLS), 

3 HLLSHEAD CHAR(28), /* Skip over header information */ 
3 HLLSLINK POINTER, /* PTR to Linkage Service Routine*/ 
3 HLLSFIL1 CHAR(8), 
3 CNMCMD ENTRY(PTR, CHAR(*) VARYING) 

OPTIONS (ASM, INTER, RETCODE) , 
3 HLLSFIL2 CHAR(4), 
3 CNMVARS ENTRY(PTR, CHAR(8), CHAR(*) VARYING, FIXED BIN(31) f 

CHAR(*) VARYING, CHAR (8)) 

OPTIONS(ASM, INTER, RETCODE) , 
3 HLLSFIL3 CHAR(4), 
3 CNMNAMS ENTRY(PTR, CHAR(8), PTR, CHAR(*) VARYING, 

FIXED BIN(31), FIXED BIN(31)) 

OPTIONS (ASM, INTER, RETCODE) , 
3 HLLSFIL4 CHAR(4), 
3 CNMGETD ENTRY(PTR, CHAR(8), CHAR(*) VARYING, FIXED BINARY(31), 

*, FIXED BINARY(31), FIXED BINARY(31)) 

OPTIONS(ASM, INTER,RETCODE) , 
3 HLLSFIL5 CHAR(4), 
3 CNMSMSG ENTRY(PTR, CHAR(*) VARYING, CHAR(8), CHAR(8), CHAR(8)) 

OPTIONS (ASM, INTER, RETCODE) , 
3 HLLSFIL6 CHAR(4), 
3 CNMINFC ENTRY (PTR, CHAR(8), CHAR(*) VARYING, FIXED BIN(31)) 

OPTIONS(ASM, INTER,RETCODE) , 
3 HLLSFIL7 CHAR(4), 
3 CNMINFI ENTRY(PTR, CHAR(8), FIXED BIN(31)) 

OPTIONS (ASM, INTER,RETCODE) , 
3 HLLSFIL8 CHAR(4), 
3 CNMGETA ENTRY (PTR, CHAR(8), CHAR(*) VARYING, 

FIXED BIN(31), FIXED BIN(31)) 

OPTIONS (ASM, INTER, RETCODE) , 
3 HLLSFIL9 CHAR(4), 
3 CNMMEMO ENTRY(PTR, FIXED BIN(31), CHAR(8), CHAR(8)) 

OPTIONS(ASM,INTER,RETCODE), 
3 HLLSFILA CHAR(4), 
3 CNMMEMR ENTRY(PTR, FIXED BIN(31), CHAR(*) VARYING, 

FIXED BIN(31)) 

OPTIONS (ASM, INTER.RETCODE), 
3 HLLSFILB CHAR(4), 
3 CNMMEMC ENTRY(PTR, FIXED BIN(31)) 

OPTIONS (ASM, INTER.RETCODE), 
3 HLLSFILC CHAR(4), 
3 CNMCNMI ENTRY(PTR, CHAR(8), CHAR(*) VARYING, CHAR(8), 

FIXED BIN(31)) 

OPTIONS (ASM, INTER, RETCODE), 
3 HLLSFILD CHAR(4), 
3 CNMSCAN ENTRY (PTR, CHAR(*) VARYING, CHAR(*) VARYING, 

FIXED BIN(31), *,*,*,*,*,*, *,*,*,*) 

OPTIONS (ASM, INTER, RETCODE) , 
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3 HLLSFILE CHAR(4), 

3 CNMKIO ENTRY(PTR, CHAR(8), CHAR(*) VARYING, FIXED BIN(31), 

CHAR(*) VARYING, CHAR (8) ) 

OPTIONS (ASM, INTER.RETCODE) , 
3 HLLSFILF CHAR(4), 
3 CNMSCOP ENTRY (PTR, CHAR(8), CHAR(8), CHAR(8)) 

OPTIONS (ASM, INTER, RETCODE), 
3 HLLSFILG CHAR(4), 
3 CNMCPYS ENTRY(PTR, PTR, PTR, FIXED BIN(31),CHAR(8)) 

OPTIONS(ASM, INTER, RETCODE), 
3 HLLSFILH CHAR(4), 
3 CNMLK ENTRY (PTR, CHAR(8), CHAR(*) VARYING, CHAR(8),CHAR(8)) 

OPTIONS (ASM, INTER, RETCODE) , 
3 HLLSFILI CHAR(4), 
3 CNMPOOL ENTRY (PTR, CHAR(8), FIXED BIN(31,0),CHAR(*) VARYING, 

FIXED BIN(31,0), FIXED BIN(31), 

FIXED BIN(31), FIXED BIN(31)) 

OPTIONS (ASM, INTER, RETCODE) , 
3 HLLSFILJ CHAR(4), 
3 CNMALTD ENTRY (PTR, CHAR(8), CHAR(*) VARYING, *, FIXED BIN(31), 

FIXED BIN(31)) 

OPTIONS (ASM, INTER, RETCODE), 
3 HLLSFILK CHAR(4) , 
3 CNMCELL ENTRY(PTR, CHAR(8), FIXED BIN(31), PTR) 

OPTIONS(ASM,INTER,RETCODE), 
3 HLLSFILL CHAR(4); 

/* Macro definitions */ 

/* Each of the HLL service routines has a macro definition which */ 

/* inserts the hlb pointer (HLBPTR) into the parameter list. */ 

/•it************************************************************ 

%DCL CNMCOMMAND ENTRY; 

%CNMCOMMAND:PROC(DATA) STATEMENT RETURNS (CHAR); 

DCL (DATA,RTNSTR) CHAR; 

RTNSTR = 'CALL CNMCMD( HLBPTR, ' | | DATA | |'); '; 

RETURN (RTNSTR); 

%END; 

%DCL CNMVARPOOL ENTRY; 

%CNMVARPOOL:PROC(FUNC,DATA,LENG,NAME,POOL) STATEMENT RETURNS(CHAR; 

DCL (FUNC,DATA, LENG, NAME, POOL, RTNSTR) CHAR; 

IF -PARMSET(LENG) THEN LENG = '0'; 

IF -PARMSET(DATA) THEN DATA = "••'•; 

RTNSTR = ' CALL CNMVARS (HLBPTR, ' 1 1 FUNC 1 1 ' , ' 1 1 DATA 1 1 ' , ' | I LENG | | • , ' 

||NAME||','||POOL||');'; 
RETURN (RTNSTR); 
%END; 
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%DCL CNMNAMESTR ENTRY; 

%CNMNAMESTR:PROC( FUNC, STRPTR, NAME, LENG, CLASS) STATEMENT RETURNS (CHAR) ; 

DCL (FUNC, STRPTR, NAME, LENG, CLASS, RTNSTR) CHAR; 

IF -PARMSET(LENG) THEN LENG = '0'; 

IF -PARMSET(STRPTR) THEN STRPTR = '(NULLQ)'; 

IF -PARMSET(CLASS) THEN CLASS = '0'; 

RTNSTR = 'CALL CNMNAMS(HLBPTR, ' | |FUNC| | ' ,' | | STRPTR | | ' ,' | | NAME | | ' ,' 

I ILENGI | ',' | (CLASS! I *);'; 
RETURN (RTNSTR); 
%END; 

%DCL CNMGETDATA ENTRY; 

%CNMGETDATA:PROC(FUNC, DATA, LENG, ORIGIN, QUEUE, LINE) 

STATEMENT RETURNS (CHAR); 
DCL (FUNC, DATA, LENG, ORIGIN, QUEUE, LINE, RTNSTR) CHAR; 
IF -PARMSET(DATA) THEN DATA = " " " ; 

IF -PARMSET(ORIGIN) THEN ORIGIN = ' ; 

IF -PARMSET(LENG) THEN LENG = '0'; 
IF -PARMSET(LINE) THEN LINE = '0'; 
RTNSTR = 'CALL CNMGETD(HLBPTR, ' 1 1 FUNC 1 1' , ' 1 1 DATA j | ' ,' | |LENG| | ' , ' 

||ORIGIN||','||QUEUE||','||LINE||');'; 
RETURN(RTNSTR); 
%END; 

%DCL CNMSENDMSG ENTRY; 

%CNMSENDMSG:PROC(DATA,MSGTYPE,DESTTYPE,DEST) STATEMENT RETURNS(CHAR) ; 

DCL (DATA, MSGTYPE,DESTTYPE,DEST, RTNSTR) CHAR; 

IF -PARMSET(DEST) THEN DEST = ; 

RTNSTR = 'CALL CNMSMSG(HLBPTR, ' | | DATA | |' , ' | |MSGTYPE| | ' ,' 

||DESTTYPE||','||DEST||');'; 
RETURN (RTNSTR); 
%END; 

%DCL CNMINFOC ENTRY; 

%CNMINFOC:PROC( ITEM, DATA, LENG) STATEMENT RETURNS (CHAR); 

DCL (ITEM, DATA, LENG, RTNSTR) CHAR; 

RTNSTR = 'CALL CNMINFC(HLBPTR,' | |ITEM| |' , ' | | DATA | | ' ,' | |LENG| | '); ' ; 

RETURN (RTNSTR); 

%END; 

%DCL CNMINFOI ENTRY; 

%CNMINFOI:PROC( ITEM, DATA) STATEMENT RETURNS (CHAR); 

DCL (ITEM, DATA, RTNSTR) CHAR; 

RTNSTR = 'CALL CNMINFI(HLBPTR, ' | |ITEM| | ' , ' | | DATA | | ');' ; 

RETURN (RTNSTR); 

%END; 

%DCL CNMGETATTR ENTRY; 

%CNMGETATTR:PROC( ITEM, DATA, LENG, QUEUE) STATEMENT RETURNS (CHAR); 

DCL (ITEM, DATA, LENG, QUEUE, RTNSTR) CHAR; 

RTNSTR = 

'CALL CNMGETA(HLBPTR, ' 1 1 ITEM] | ' , ' 1 1 DATA 1 1« , ' 1 1 LENG) | ' , ' | |QUEUE| | ') ; ' ; 

RETURN (RTNSTR); 

%END; 
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%DCL CNMOPENMEM ENTRY; 

%CNMOPENMEM:PROC(TOKEN,DATASET,MEMBER) STATEMENT RETURNS (CHAR); 

DCL (TOKEN, DAT ASET, MEMBER, RTNSTR) CHAR; 

RTNSTR = 

'CALL CNMMEMO(HLBPTR, ' | | TOKEN | | ' , ' | |DATASET| | ' , ' | | MEMBER | | ') ; ' ; 

RETURN (RTNSTR); 

%END; 

%DCL CNMREADMEM ENTRY; 

%CNMREADMEM:PROC (TOKEN, DATA, LENG) STATEMENT RETURNS (CHAR); 

DCL (TOKEN, DATA, LENG, RTNSTR) CHAR; 

RTNSTR = 'CALL CNMMEMR(HLBPTR, ' 1 1 TOKEN 1 1 ' , ' 1 1 DATA 1 1 ' , ' 1 1 LENG 1 1 ') ; ' ; 

RETURN (RTNSTR); 

%END; 

%DCL CNMCLOSMEM ENTRY; 

%CNMCLOSMEM:PROC (TOKEN) STATEMENT RETURNS (CHAR); 

DCL (TOKEN, RTNSTR) CHAR; 

RTNSTR = 'CALL CNMMEMC(HLBPTR, ' | | TOKEN || '); ' ; 

RETURN (RTNSTR); 

%END; 

%DCL CNMI ENTRY; 

%CNMI:PROC(FUNC, DATA, DEST, TIMEOUT) STATEMENT RETURNS (CHAR) ; 

DCL (FUNC, DATA, DEST, TIMEOUT, RTNSTR) CHAR; 

IF -PARMSET (TIMEOUT) THEN TIMEOUT = '0'; 

RTNSTR = ' CALL CNMCNMI (HLBPTR, * | | FUNC I | ' , ' | | DATA | | ' , ' | | DEST | |' , ' 

IITIMEOUTM');'; 
RETURN (RTNSTR); 
%END; 

%DCL CNMSSCAN ENTRY; 

%CNMSSCAN:PROC(DATA, FORMAT, COUNT, PI, P2,P3,P4,P5,P6,P7,P8,P9,P10) 

STATEMENT RETURNS (CHAR) ; 
DCL (DATA, FORMAT, COUNT, PI, P2,P3,P4,P5,P6,P7,P8,P9,P10, RTNSTR) CHAR; 
IF -PARMSET(Pl) THEN PI = '0' 
IF -PARMSET(P2) THEN P2 = '0' 
IF -PARMSET(P3) THEN P3 = '0' 
IF -PARMSET(P4) THEN P4 = '0' 
IF -PARMSET(P5) THEN P5 = '0' 
IF -PARMSET(P6) THEN P6 = '0' 
IF -PARMSET(P7) THEN P7 = '0' 
IF -PARMSET(P8) THEN P8 = '0' 
IF -PARMSET(P9) THEN P9 = '0' 
IF -PARMSET(PIO) THEN P10 = '0'; 
RTNSTR = ' CALL CNMSCAN (HLBPTR, ' 1 1 DATA 1 1 ' , ' | 1 FORMAT 1 1 ' , ' 1 1 COUNT | 

||P1||','1|P2||','||P3|||','||P4|| I ,'||P5|| , ,'||P6||',' 

1 1 P7 M ' . • II PS 1 1 ' » ' 1 1 P9 M * , ' II P10 M ■ ) ; • ; 
RETURN (RTNSTR); 
%END; 



i i 
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%DCL CNMKEYIO ENTRY; 

%CNMKEYIO:PROC(FUNC,DATA,LENG, KEY, OPTIONS) STATEMENT RETURNS(CHAR) ; 

IF -PARMSET(DATA) THEN DATA = "•'•'; 

IF -PARMSET(LENG) THEN LENG = '0'; 

IF -PARMSET(KEY) THEN KEY = ■"•••; 

IF -PARMSET (OPTIONS) THEN OPTIONS = ""•'; 

DCL (FUNC, DATA, LENG, KEY, OPTIONS, RTNSTR) CHAR; 

RTNSTR = 'CALL CNMKIO(HLBPTR, ' | | FUNC | | ' , ' | | DATA | | ' , ' | |LENG| | ' , ' 

1 1 KEY 1 1 ' , » | ! OPTIONS 1 1 ' ) ; • ; 
RETURN (RTNSTR); 
%END; 

%DCL CNMSCOPECK ENTRY; 

%CNMSCOPECK:PROC(VERB, KEYWORD, VALUE) STATEMENT RETURNS (CHAR); 

DCL (VERB, KEYWORD, VALUE, RTNSTR) CHAR; 

IF -PARMSET(VERB) THEN VERB = " " ' ' ; 

IF -PARMSET (KEYWORD) THEN KEYWORD = •••'••; 

IF -PARMSET (VALUE) THEN VALUE * ; 

RTNSTR = 'CALL CNMSCOP(HLBPTR, ' | |VERB| | ' , ' | | KEYWORD { | « , ' | | VALUE| | ') ; ' ; 

RETURN (RTNSTR); 

%END; 

%DCL CNMCOPYSTR ENTRY; 

%CNMC0PYSTR:PROC (FROM, TO, LENG, COPYTYPE) STATEMENT RETURNS (CHAR) ; 

DCL (FROM,TO, LENG, COPYTYPE, RTNSTR) CHAR; 

RTNSTR = 

'CALL CNMCPYS(HLBPTR, ' | | FROM| | ' , ' | | TO | | ' , ' | | LENG| | ' , ' | |COPYTYPE| | ' ) ; ' ; 

RETURN (RTNSTR); 

%END; 

%DCL CNMLOCK ENTRY; 

%CNMLOCK:PROC(FUNC, NAME, SCOPE, OPTION) STATEMENT RETURNS(CHAR) ; 

DCL (FUNC, NAME, SCOPE,OPTION, RTNSTR) CHAR; 

IF -PARMSET (SCOPE) THEN SCOPE = ' ; 

IF -PARMSET (OPTION) THEN OPTION = ; 

RTNSTR = 

' CALL CNMLK(HLBPTR, ' 1 1 FUNC 1 1 ' , ' 1 1 NAME 1 1 ' , ' 1 1 SCOPE 1 1 • , ' 1 1 OPTION 1 1 ' ) ; ' ; 

RETURN (RTNSTR); 

%END; 

%DCL CNMSTRPOOL ENTRY; 

%CNMSTRPOOL:PROC(FUNC, TOKEN, NAME, LENG, PRICELLS,SECCELLS, CLASS) 

STATEMENT RETURNS (CHAR); 
DCL ( FUNC, TOKEN, NAME, LENG, PRICELLS,SECCELLS, CLASS, RTNSTR) CHAR; 
IF -PARMSET (TOKEN) THEN TOKEN = '0'; 
IF -PARMSET(LENG) THEN LENG = '0'; 

IF -PARMSET(PRICELLS) THEN PRICELLS = '0'; 
IF -PARMSET(SECCELLS) THEN SECCELLS = '0'; 
IF -PARMSET (CLASS) THEN CLASS = '0'; 
RTNSTR = 'CALL CNMP00L(HLBPTR,' | | FUNC | | ' ,' | | TOKEN | | ' ,' | |NAME|| ' , ' 

1 1 LENG 1 1 ' , ' 1 1 PRICELLSj | ' , ' | (SECCELLS 1 1' , ' 1 1 CLASS 1 1 ' ) ; ' ; 
RETURN (RTNSTR); 
%END; 
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d)CL CNMALTDATA ENTRY; 

&NMALTDATA:PROC(FUNC, DATA, ORIGIN, QUEUE, LINE) STATEMENT RETURNS (CHAR) ; 

)CL (FUNC,DATA,ORIGIN,QUEUE,LINE,RTNSTR) CHAR; 

T -PARMSET(DATA) THEN DATA = ' ' " " ; 

F -PARMSET (ORIGIN) THEN ORIGIN = ' ; 

TNSTR = 'CALL CNMALTD(HLBPTR, • | |FUNC| | ' , ' | 1 DATA | | « , • | |ORIGIN| | ' , ' 
IIQUEUEH'.'IILINEH');'; 

TURN(RTNSTR); 
ND; 

tL CNHSTRCELL ENTRY; 

MSTRCELL: PROC(FUNC, TOKEN, STRPTR) STATEMENT RETURNS (CHAR) ; 
(FUNC, TOKEN, STRPTR,RTNSTR) CHAR; 

»TR = 'CALL CNMCELL(HLBPTR,M|FUNC|| VIITOKENIIVIISTRPTRII');'; 
'RN(RTNSTR); 
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DSIPCNM 












/A********************************************************** 




/* 






7 




/* 


NAME = DSIPCNM 




7 




/* 






7 




/* 


DESCRIPTIVE NAME = HLL PL/I Return Codes 




7 




/* 






7 




/* 


5665-362 for MVS/XA 




7 




/* 


THIS PRODUCT CONTAINS 




7 




/* 


"RESTRICTED MATERIAL OF IBM" 




7 




/* 


(c) COPYRIGHT IBM CORP 1989 




7 




/* 


ALL RIGHTS RESERVED 




7 




/* 


LICENSED MATERIALS-PROPERTY OF IBM 




7 




/* 


REFER TO COPYRIGHT INSTRUCTION FORM 




7 




/* 


NUMBER G120-2083 




7 




/* 






7 




/* 


STATUS - NetView Release 3 




7 




/* 






7 




/* 


FUNCTION = This file defines the HLL return codes 


for PL/I. */ 




/* 






7 




/* 


NOTES - see below 




7 




/* 






7 




/* 


DEPENDENCIES = none 




7 




7* 






7 




/* 


RESTRICTIONS = none 




7 




/* 






7 




/* 


REGISTER CONVENTIONS = not applicable 




7 




/* 






7 




/* 


PATCH LABEL = not applicable 




7 




/* 






7 




/* 


MODULE TYPE = constants 




7 




/* 






7 




/* 


PROCESSOR = PL/I 




7 




/* 






7 




/* 


EXTERNAL REFERENCES = none 




7 




/* 






7 




/* 


CHANGE ACTIVITY 




7 




/* 






7 




/***********************************^ 




%DCL CNM GOOD FIXED; %CNM GOOD 


=0; 






%DCL CNM_BAD INVOCATION FIXED; %CNM BAD INVOCATION 


=4; 






%DCL CNM TOO MANY FIXED; %CNM TOO MANY 


=8; 






%DCL CNMJAD SYNTAX FIXED; %CNM_BAD_SYNTAX 


=12, 






%DCL CNM BAD DDNAME FIXED; %CNM BAD DDNAME 


=16 






%DCL CNM NOT FOUND FIXED; %CNM NOT FOUND 


=20; 






%DCL CNM NO STORAGE FIXED; %CNM NO STORAGE 


=24 






%DCL CNM_IOERROR FIXED; %CNM_IOERROR 


=28 






%DCL CNM BAD TOKEN FIXED; %CNM BAD TOKEN 


=32 






%DCL CNM END FILE FIXED; %CNM END FILE 


=36 






%DCL CNM_DATA TRUNC FIXED; %CNM DATA_TRUNC 


=40 






%DCL CNM JOT IN ASYNC FIXED; %CNM NOT IN ASYNC 


=44 
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%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 

%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 
%DCL 



cnm_bad_ruleng 

cnm bad_func 

cnmIbadjimeout 

cnm_need_prid 

cnm_neg_response 

cnm_time_out 

cnm_bad_queue 

cnm_bad_index 

cnm_queue_empty 

cnm bad_origblock 

cnm~bad_length 

cnm_not_mlwto 

cnm_bad_linetype 

cnm_nocur_line 

cnm_dupl_name 

cnm~bad_name 

cnm_bad_class 

cnm_bad_msgtyp 

cnm_bad_destyp 

cnm~typ_conflict 

cnm_bad_option 

cnm_command_na 

cnm keywordja 

cnmjalue na 

cnm_bad_command 

cnm_bad_keyword 

cnm_no_trap 

cnm_bad_pool 

cnm_bad_addr 

cnm_bad_taskname 

cnm bad_modname 

cnmjadjd 

cnm_bad_combo 

cnm_tvb_inuse 

cnm_rid_inuse 

cnm_rid_self 

cnm_bad_pri_count 

cnm_bad_sec_count 

cnm_dupl_key 

cnm_not_in_pool 

cnm_locked 

cnm_lock_inuse 

cnm_log_inactive 

cnm_task_inactive 

cnm_time_out_wait 

cnm_go on_wait 

cnm msg on wait 



FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 
FIXED 



%CNM 

%CNM_ 

%CNM~ 

%cnm" 
%cnm" 

%CNM~ 
%CNM_ 
%CNM 
%CNM~ 

%cnm" 
%cnm" 
%cnm" 
%cnm" 

%CNM 
%CNM 
%CNM~ 

%cnm" 

%CNM_ 
%CNM 

%cnm" 
%cnm] 
%cnm" 
%cnm" 
%cnm[ 
%cnm" 
%cnm] 
%cnm" 
%cnm" 
%cnm" 



BAD_RULENG 

BAD_FUNC 

BADJIMEOUT 

NEED_PRID 

NEG_RESPONSE 

TIME_OUT 

BAD_QUEUE 

BAD_INDEX 

QUEUE_EMPTY 

BAD_ORIGBLOCK 

BAD_LENGTH 

NOT MLWTO 

BADJ.INETYPE 

NOCUR_LINE 

DUPL_NAME 

BAD_NAME 

BAD_CLASS 

BAD_MSGTYP 

BAD_DESTYP 

TYP_CONFLICT 

BAD_OPTION 

COMMAND_NA 

KEYWORDJA 

VALUEJA 

BAD_COMMAND 

BAD_KEYWORD 

"NOJRAP 

BAD_POOL 

BAD ADDR 



=48 

=52 

=56 

=60 

=64 

=68 

=72 

=76 

=80 

=84 

=88 

=92 

=96; 

=100 

=104 

=108 

=112 

=116 

=120 

=124 

=128 

=132 

=136 

=140 

=144 

=148 

=152 

=156 

=160 



FIXED; %CNM_BAD_TASKNAME =164 

FIXED; %CNM~BAD_MODNAME =168 

FIXED; %CNM_BAD_ID =172 

FIXED; %CNM_BAD_COMBO =176 

FIXED; %CNM TVBJNUSE =180 

FIXED; %CNM~RID_INUSE =184 

FIXED; %CNM_RID_SELF =188 

FIXED; %CNM_BAD_PRI_COUNT =192 

FIXED; %CNM_BAD_SEC_COUNT =196 

FIXED; %CNM_DUPL_KEY =200; 

FIXED; %CNM_NOT IN POOL =204; 



FIXED; %CNM_LOCKED =208; 

FIXED; %CNM LOCKJNUSE =212; 

FIXED; %CNM~LOG_INACTIVE =216; 

FIXED; %CNM~TASK_INACTIVE =220; 

FIXED; %CNM_TIME_OUT_WAIT =224; 

FIXED; %CNM GO_ON_WAIT =228; 

FIXED; %CNMJ1SG_0N_WAIT =232; 

CNM_OPINPUT_ON_WAIT FIXED; %CNM_0PINPUT_0N_WA=236; 
CNM DATA_ON_WAIT FIXED; %CNM_DATA_ON_WAIT =240; 
CNMJO_TRAP_SET FIXED; %CNM_NO_TRAP_SET =244; 

CNM_NO~PREV_WAIT FIXED; %CNM~NO_PREV_WAIT =248; 
CNM BAD_CSTYPE FIXED; %CNM_BAD_CSTYPE 52; 

CNM~BAD_CELL_ADDRESS FIXED; %CNM_BAD_CELL_ADDRESS=256; 
CNM_CELL_ALREADY_FREE FIXED; %CNM_CELL_ALREADY_FREE=260; 
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%DCL CNM BAD MQS 


FIXED 


, %CNM BAD MQS 


=1000; 


%DCL CNM DST~FAILURE 


FIXED 


, %CNM DST~ FAILURE 


=2000; 


%DCL CNM BAD~EXCMS 


FIXED 


%CNM~BAD~EXCMS 


=3000; 


%DCL CNM BAD PUSH 


FIXED 


%CNM BAD~PUSH 


=4000; 


%DCL CNM BAD POP 


FIXED 


, %CNM BAD POP 


=5000; 


%DCL CNM"BAD""WLS 


FIXED 


, %CNM BAD~~WLS 


=6000; 


%DCL CNM~BAD~PSS 


FIXED- 


%CNM~BAD PSS 


=7000; 


%DCL CNM""BAD""WT0 


FIXED 


%CNM BAD~WTO 


=8000; 


%DCL CNM BAD CES 


FIXED 


%CNM~BAD~CES 


=9000; 


%DCL CNM~BAD~DKS 


FIXED- 


, %CNM_BAD~DKS 


=10000; 


%DCL CNM~BAD KVS 


FIXED- 


%CNM BAD~KVS 


=11000; 


%DCL CNM~BAD~LOAD 


FIXED 


%CNM~BAD LOAD 


=12000; 


%DCL CNMJAD_LCS 


FIXED 


%CNM~BAD LCS 


=13000; 


%DCL CNM~BAD CDS 


FIXED 


%CNM BAD~CDS 


=14000; 


%DCL CNM~BAD~ESTAE 


FIXED- 


%CNM BAD ESTAE 


=15000; 


%DCL CNM~BAD_PAS 


FIXED 


%CNM BAD~PAS 


=16000; 


%DCL CNM~BAD~SNTXS 


FIXED 


%CNM BAD~SNTXS 


=17000; 


%DCL CNM~BAD~MRBLD 


FIXED 


, %cnm_bad"mrbld 


=18000; 


%DCL CNM BAD ZCSMS 


FIXED 


, %CNM BAD ZCSMS 


=20000; 


%DCL CNM_BAD_ENQ 


FIXED 


%CNM_BAD_ENQ 


=21000; 
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Appendix B. PL/I Samples 



This appendix contains a table of the pl/i samples that are shipped with NetView in 
syslcnmsamp. When data set names are referred to in this appendix, two names 
are given, such as ptmpplt (CNMS4200). The first name is the alias name, and the 
name in parenthesis is in the NetView samples library. You can use either name to 
access the samples, dsicmd has definitions for the alias names to allow those 
names to be entered as commands. 

The following steps allow you to enter the member names as commands: 

1. Compile and link edit the samples using the alias name. 

2. Delete the (*) in column one of the appropriate cmdmdl statement in dsicmd to 
be able to execute the alias name as a command. No entries are needed in 
dsicmd for user exits. 

3. NetView must be recycled to pick up the dsicmd changes. 

Notes: 

1. See the prologues of the samples for information about how certain samples 
are related and special cases for user exit routines. 

2. Each alias name for pl/i begins with the letter P. 

3. The alias name is the same as the procedure name, which is limited to seven 
characters, in pl/i. 

This appendix also contains a description of each sample, and coded samples of a 
user exit routine and two command processors. 
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PL/I Samples Table 



The following table refers to the pl/i samples that are shipped with NetView. The 
table contains the function, the alias name, and the name of the member in 

SYS1:GNMSAMP. 

Sample function 



Template for commands and user exit routines 

Sample DSIEX03 to set a global variable 

Uses CNMSMSG to send data 

Uses WAIT FOR DATA 

Sample DSIEXG2A changes a WTO to an MLWTO 

Uses CNMCNMI to forward RUs to a PU 

Uses CNMKIO for I/O to VSAM 

HLL command using CNMSCOP for scope checking 

Display full screen VIEW panel 

Activates LU and uses TRAP and WAIT to 

determine if activation is successful 

Uses CNMSMSG to log text to a sequential log 

DST initialization exit USERVSAM DST 

Primes VSAM empty data set for USERVSAM DST 

Sends a request to USERVSAM DST 

Processes VSAM requests under USERVSAM DST 

Primes VSAM empty data set for PKEYIO 



PL/I 


Sample 


Alias 


CNMSAMP 


PTMPPLT 


CNMS4200 


PEXIT3 


CNMS4210 


PSNDDAT 


CNMS4211 


PWATDAT 


CNMS4212 


PEXIT2A 


CNMS4213 


PCNMI 


CNMS4214 


PKEYIO 


CNMS4215 


PSCOPCK 


CNMS4216 


PFLVIEW 


CNMS4217 


PACTLU 


CNMS4218 


PSEQLOG 


CNMS4219 


PXITDI 


CNMS4220 


PXITVN 


CNMS4221 


PSNDDST 


CNMS4222 


PDOVSAM 


CNMS4223 


PPRIME 


CNMS4224 
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PL/I Samples Description 



For each sample, a description of the function and the hll service routines utilized 
are given. 

PTMPPLT (CNMS4200) 

This sample is a template for commands and user exit routines in pl/i. 

This sample is included in Chapter 5 on page 37. 

PEXIT3 (CNMS4210) 

This is a sample dsiexo3 that sets a task global variable. This global variable will 
contain the value of the last time that a command other than psnddat was entered 
under an ost. pwatdat and psnddat are used to interrogate this value. 

The hll service routines utilized in this sample are: cnminfc (CNminfoc), cnmvars 

(CNMVARPOOL). 

PSNDDAT (CNMS4211) 

This sample uses cnmsmsg to send data. The sample is part of an example of 
sending messages with a type of request, waiting on the response, and parsing the 
results. 

The purpose of the example is to find the last time that a command was entered on 
a given ost. A task global variable is set by pexits every time a command is 
entered on an ost. pwatdat uses cnmsmsg to issue a psnddat on the task in ques- 
tion, pwatdat then goes into a wait state, psnddat retrieves the value of the global 
variable and uses cnmsmsg to send the data back to the task that issued the 
pwatdat. pwatdat breaks out of the wait state (it has received the data it was 
waiting for), and parses and displays the data. 

The hll service routines utilized in this sample are: cnmvars (Cnmvarpool), 

CNMSMSG (CNMSENDMSG), CNMINFC (CNMINFOC). 

PWATDAT (CNMS4212) 

This sample uses wait for data. The sample is part of an example of sending mes- 
sages with a type of request, waiting on the response, and parsing the results. 

The purpose of the example is to find the last time that a command was entered on 
a given ost. A task global variable is set by pexit3 every time a command is 
entered on an ost. pwatdat uses cnmsmsg to issue a psnddat on the task in ques- 
tion, pwatdat then goes into a wait state, psnddat retrieves the value of the global 
variable and uses cnmsmsg to send the data back to the task that issued the 
pwatdat. pwatdat breaks out of the wait state (it has received the data it was 
waiting for), and parses and displays the data. 

The hll service routines utilized in this sample are: cnmsmsg (Cnmsendmsg), 

CNMSCAN (CNMSSCAN), CNMCMD (CNMCOMMAND), CNMGETD (CNMGETDATA). 
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PEXIT2A (CNMS4213) 

This sample exit converts a wto to an mlwto by adding two lines to the single-line 
wtos that are driving the exit. 

The hll service routines utilized in this sample are: cnmgetd (Cnmgetdata), cnmaltd 

(CNMALTDATA). 

This sample is included in "Sample User Exit" on page 269. 

PCNMI (CNMS4214) 

This sample uses cnmcnmi to forward rus to a pu. NetView provides the cnmcnmi 
service routine for use in communicating with devices in the network through the 
Communications Network Management Interface (cnmi). Any data that is returned 
may be accessed using the cnmgetd service routine to retrieve records from the 
cnmi solicited data queue (cnmiq). 

This sample uses the cnmcnmi service routine to send a product set io data request 
to a specified pu. Any data returned is sent as a message to the operator. The 
prologue of the sample contains instructions for set up. 

The hll service routines utilized in this sample are: cnmscan (Cnmsscan), cnmcnmi 

(CNMI), CNMGETD (CNMGETDATA), CNMSMSG (CNMSENDMSG). 

PKEYIO (CNMS4215) 

This sample illustrates how to code a NetView hll command processor that allows 
i/o to a vsam file via the cnmkio service routine. It must execute on a dst. To run 
this command on a dst, either use the excmd command or the cnmsmsg service 
routine (with a type of command). The prologue of the sample explains how to set 
up a DST. 

The hll service routines utilized in this sample are: cnmkio (Cnmkeyio), cnmsmsg 

(CNMSENDMSG). 

PSCOPCK (CNMS4216) 

This sample illustrates the scope checking capabilities provided by NetView. This 
sample scope checks keywords and values of the pscopck command. In this 
sample, the user is required to set up the following elements for the command: 
operator id, operator classes that can access the command, and operator profile. 
See the prologue of the sample for more information. This command yields a 
message informing the operator if he is not authorized to use the keyword and 
value specified when invoking the command. 

The hll service routines utilized in this sample are: cnmscan (cnmsscan), cnmscop 

(CNMSCOPECK), CNMSMSG (CNMSENDMSG). 

This sample is included in "Sample Command Processor for Scope Checking" on 
page 272. 



266 NetView Customization: Using PLI and C 



PFLVIEW (CNMS4217) 

This sample illustrates the usage of the full screen view command processor. 

The hll service routines utilized in this sample are: cnmcmd (Cnmcommand), 

CNMVARS (CNMVARPOOL). 

PACTLU (CNMS4218) 

This sample illustrates how to issue a vtam command to activate an lu, trap the 
vtam messages that result, and respond depending on the messages received. 

The hll service routines utilized in this sample are: cnmscan (CNmsscan), cnmcmd 

(CNMCOMMAND), CNMGETD (CNMGETDATA), CNMSMSG CNMSENDMSG). 

PSEQLOG (CNMS4219) 

This sample uses cnmsmsg to log text to a sequential log. The prologue of the 
sample contains instructions for set up. 

The hll service routines utilized in this sample are: cnmscan (Cnmsscan), cnminfc 

(CNMINFOC), CNMSMSG (CNMSENDMSG). 

This sample is included in "Sample Command Processor for Sequential Logging" 
on page 276. 

PXITDI (CNMS4220) 

This sample is a dst initialization exit. The sample illustrates the dst initialization 
exit that is used by the uservsam dst. 

The hll service routines utilized in this sample are: cnmvars (CNmvarpool), 

CNMSMSG (CNMSENDMSG). 

PXITVN (CNMS4221) 

This sample primes a vsam empty data set for the uservsam dst. 

PSNDDST (CNMS4222) 

This sample sends a 'put' or 'get' request to the sample hll Data Services 
Command Processor named pdovsam to store and retrieve a given value for a 
specified key (key and value limited to 11 characters in length). The sample also 
allows a specified NetView Command List Language variable (defined by the 
caller) to be set to the retrieved value. 

The hll service routines utilized in this sample are: cnmscan (cnmsscan), cnmsmsg 

(CNMSENDMSG), CNMVARS (CNMVARPOOL), CNMGETD (CNMGETDATA), CNMCMD (CNMCOMMAND). 

PDOVSAM (CNMS4223) 

This sample is an hll Data Services Command Processor which runs under the 
sample Data Services Task (task id 'uservsam'). It processes 'put' or 'get' requests 
sent by the psnddst sample, and will write or read an 11 character value associ- 
ated with an 1 1 character key to the sample dst's vsam data set. The prologue of 
pdovsam contains instructions on installing the sample 'uservsam' Data Services 
Task. 
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The hll service routines utilized in this sample are: cnmscan (CNMsscan), cnmsmsg 

(CNMSENDMSG), CNMKIO (CNMKEYIO). 

PPRIME (CNMS4224) 

This sample primes a vsam empty data set for pkeyio. 
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PL/I Coded Samples 



This section contains an example of a user exit routine and two command 
processors. 

Sample User Exit 

This sample is an example of user exit dsiexo2a. 
PEXIT2A: PROC(HLBPTR,CMDBUF,ORIGBLCK) OPTIONS (MAIN, REENTRANT); 

/* V 

/* (C) COPYRIGHT IBM CORP. 1989 */ 

/* */ 

/* IEBCOPY SELECT MEMBER=((CNMS4213,PEXIT2A,R)) */ 

/* */ 

/* Descriptive Name: High Level Language PL/I DSIEX02A */ 

/* Exampl e */ 

/* V 

/* Function: */ 

/* */ 

/* This DSIEX02A adds two lines to the single line WTOs */ 

/* that are driving the exit. */ 

/* */ 

/* Introduction: */ 

/* */ 

/* To convert a single line WTO into a multi-line WTO, */ 

/* you must change the line types accordingly: */ 

/* V 

/* In Out */ 

/* — — */ 

/* msg_type = "E",msg_type="=" line_type="C" (Control) */ 

/* and a msg_type="=" line_type="D" (Data) */ 

/* line_type of " " msg_type="=" line type="F" (Final) */ 

/* " V 

/* Note: */ 

/* A Msg_type of "E" implies that the message was externally */ 

/* generated via a WTO. For example MVS D T would send */ 

/* a Msg_type of "E". The Msg_type of "=" implies a user */ 

/* generated MLWTO was issued. */ 

/* 7 

/* Dependencies: None */ 

/* V 

/* Restrictions: Only processes messages issued under mainline */ 

/* processing. */ 

/* */ 

/* Language: PL/I */ 
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/* V 

/* Input: */ 

/* 1) 4-byte pointer to the HLB control block */ 
/* 2) varying length character string of command (or message */ 

/* for user exits) that invoked this procedure */ 
/* 3) 40-byte parameter list which describes the origin of */ 

/* the request that caused execution of this procedure. */ 

/* */ 

/* Output: */ 

/* Messages to various tasks. */ 

/* 7 

/* Return Codes: returned in HLBRC */ 

/* = normal exit */ 

/* 7 

/* External Module References: None */ 

/* 7 

/* Change Activity: */ 

/* date, author: Description of changes */ 

/* 7 

/* 7 

/* Parameter Declarations */ 

/* 7 

DCL HLBPTR PTR; /* Pointer to the HLB */ 

%INCLUDE DSIPLI; /* Include the HLL macros */ 

DCL CMDBUF CHAR(*) VARYING; /* Buffer for the command */ 

DCL ORIGBLCK CHAR(40); /* Area for the Orig Block */ 

DCL ORIGIN PTR; /* Pointer to the Orig Block */ 

DCL ADDR BUILTIN; /* Builtin function */ 

ORIGIN=ADDR(ORIGBLCK); /* Address the Orig Block */ 

/* 7 

/* Other Declarations */ 

/* 7 

DCL GETBLOCK CHAR(40); /* Area for the Orig Block */ 

DCL DATAIN CHAR(255) VAR; /* Message that drove the exit */ 
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/••A*****************************************************************/ 

/* 7 

/* Execution */ 

/* 7 

/A*******************************************************************/ 



GETPTR=ADDR(GETBLOCK); 


/* Address the Orig block 


7 


CNMGETDATA 


/* Peek the msg before altering 


7 


FUNC('PEEKLINE') 


/* ...subf unction is PEEK 


7 


QUEUE (IDATAQ) 


/* ...initial data queue 


7 


DATA(DATAIN) 


/* ...result goes here 


7 


LENG(256) 


/* ...max length is 256 


7 


ORIGIN (GETBLOCK) 


/* ...use new Orig block 


7 


LINE(l); 


/* ...check the first line 


7 


IF GETPTR->ORIG MSG TYPE ='E' TH 
DO; 
GETPTR->ORIG MSG TYPE = ' = '; 


EN /*WT0 response to MVS command 


7 


/* Set msg type to MLWTO 


7 


GETPTR->ORIG LINE TYPE='C; 


/* Set line type to control 


7 


CNMALTDATA 


/* Replace the text ... 


7 


FUNC('REPLINE') 


/* ...function is replace 


7 


QUEUE( IDATAQ) 


/* ...initial data queue 


7 


DATA ('Change WTO to MLWTO, 


WTO="'||DATAINM"") 






/* ...text of new message 


7 


ORIGIN (GETBLOCK) 


/* ...use Peeked Orig block 


7 


LINE(l); 


/* ...replace the first line 


7 


GETPTR->ORIG LINE TYPE='D'; 


/* Set line type to data 


7 


CNMALTDATA 


/* Insert a new line... 


7 


FUNC('INSLINE') 


/* ...function is insert 


7 


QUEUE (IDATAQ) 


/* ...initial data queue 


7 


DATA ('Add a data line to the MLWTO') 




ORIGIN (GETBLOCK) 


/* ...use Peeked Orig block 


7 


LINE(2); 


/* ...add a line 


7 


GETPTR->ORIG LINE TYPE='F'; 


/* Set line type to final line 


7 


CNMALTDATA 


/* Insert a new line... 


7 


FUNC('INSLINE') 


/* ...function is insert 


7 


QUEUE (IDATAQ) 


/* ...initial data queue 


7 


DATA ('Add an end of MLWTO 


msg') 




ORIGIN (GETBLOCK) 


/* ...use Peeked Orig block 


7 


LINE(3); 


/* ...add a line 


7 



HLBRC=CNM_G0OD; /* Issue clean re... 

END; 
END PEXIT2A; 
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Sample Command Processor for Scope Checking 

This sample is an example of a command processor for scope checking. 

PSCOPCK: PROC(HLBPTR,CMDBUF,ORIGBLCK) OPTIONS (MAIN, REENTRANT); 

/•A************************************************************* 

/* 7 

/* (C) COPYRIGHT IBM CORP. 1989 */ 

/* 7 

/* IEBCOPY SELECT MEMBER=((CNMS4216, PSCOPCK, R)) */ 

/* 7 

/* Descriptive Name: High Level Language PL/I */ 

/* Scope Check Example */ 

/* 7 

/* Function: */ 

/* */ 

/* The following is an example of the scope checking capabilities */ 

/* provided by NetView. In this example, the user is required to */ 

/* set up the following elements for the command (shown below): */ 

/* (1) operator id */ 

/* (2) operator classes that can access the command */ 

/* (3) operator profile */ 

/* 7 

/* The command gives the return code that the scope check service */ 

/* routine returned to the operator. */ 

/* 7 

/* The syntax that this command checks for is: */ 

/* 7 

/* PSCOPCK PARMx(VALx) 7 

/* 7 

/* The following is the setup for the scope check example: */ 

/* 7 

/* In DSIPARM(DSICMD): */ 

/* Define the operator classes that can access */ 
/* the command, its keywords, and its keyword values. 7 

/* 7 

/* The example below says that the command HLLSCOPE */ 

/* can be executed by operators in scope class */ 

/* 1 and 2. Scope class 1 can issue any keyword */ 

/* or keyword value, but scope class 2 cannot use */ 

/* the value of VAL1 with keyword PARM2, and scope */ 

/* class 2 cannot issue PARM3 at all. */ 

I* 7 

/* Example: 7 

/* 7 

/* HLLSCOPE CMDMDL MOD=HLLMOD,RES=N,TYPE=RD */ 

/* CMDCLASS 1,2 7 

/* PARM2 KEYCLASS 1,2 */ 

/* VAL1 VALCLASS 1 */ 

/* PARM3 KEYCLASS 1 */ 

/* VAL1 VALCLASS 1 */ 

/* 7 
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/* In DSIPARM(DSIOPF) */ 

/* Define the operator ids and the profiles that the operator */ 

/* ids can use. */ 

/* V 

/* Example: */ 

/* JOE OPERATOR PASSWORD=USER */ 

/* PROFILEN DSIPR0F3 */ 

/* V 

/* In DSIPRF(profilename) */ 

/* Define the operator class value that will correspond to the */ 

/* profile that the operator logs on with. */ 

/* V 

/* Example: */ 

/* In the DSIPRF dataset, member name DSIPR0F3, */ 

/* V 

/* DSIPR0F3 PROFILE */ 

/* OPCLASS 3 */ 

/* END */ 

/* */ 

/* Restrictions: None */ 

/* V 

/* Language: PL/I */ 

/* V 

/* Input: */ 

/* 1) 4-byte pointer to the HLB control block */ 

/* 2) varying length character string of command (or message */ 

/* for user exits) that invoked this procedure */ 

/* 3) 40-byte parameter list which describes the origin of */ 

/* the request that caused execution of this procedure. */ 

/* */ 

/* Output: • */ 

/* Messages describing the scope of the operator. */ 

/* */ 

/* Return Codes: returned in HLBRC */ 

/* = normal exit */ 

/* -5 = cancelled */ 

/* V 

/* External Module References: None */ 

/* V 

/* Change Activity: */ 

/* date, author: description of changes */ 

/it******************************************************************* / 
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******************************************************************** 



/ 
/* 

/* Parameter Declarations 

/* V 

/********************************************************************/ 



/ 

V 
7 



DCL HLBPTR PTR; 

%INCLUDE DSIPLI; 

DCL CMDBUF CHAR(*) VARYING; 

DCL ORIGBLCK CHAR(40); 

DCL ORIGIN PTR; 

DCL ADDR BUILTIN; 

ORIGIN=ADDR(ORIGBLCK); 



/* 
/* 
/* 
/* 
/* 
/* 
/* 



Pointer to the HLB 
Include the HLL macros 
Buffer for the command 
Area for the Orig Block 
Pointer to the Orig Block 
Bui 1 tin function 
Address the Orig Block 



7 
7 

7 
7 
7 
7 

*/ 



/********************************************************************/ 

/* 7 

/* Other Declarations */ 

/* 7 

/********************************************************************/ 

*/ 

7 
7 
7 
7 

*/ 

V 
7 



DCL INBUF CHAR(80) 


VAR 


DCL CMDNAMEV CHAR (8) 


VAR 


DCL KEYWORDV CHAR (8) 


VAR 


DCL KEYVALUEV CHAR (8) 


VAR 


DCL CMDNAME CHAR (8); 




DCL KEYWORD CHAR(8); 




DCL KEYVALUE CHAR(8); 




DCL CNT FIXED BIN(31,0 


); 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



Buffer area 
Command that 
Keyword of i 
KeyValue of 
Command that 
Keyword of i 
KeyValue of 
Number of el 



for messages 
invoked us 
nvocation 
invocation 
invoked us 
nvocation 
invocation 
ements parsed 



/********************************************************************/ 

/* V 

/* Execution */ 

/* */ 

/********************************************************************/ 



******************************************************************** 



/ 
I* 
I 

CALL CNMSCAN (HLBPTR, 
CMDBUF, 



Scan the keyword and the value 



/ 



••••••••♦••••A******************************************************, 



/* 
/* 
/* 
/* 
/* 



Parse the input ... 
...command line is the input 
SYNTAX OF COMMAND IS: 
CMDNAME KEYWORD (KEYVALUE) 



V 
V 
*/ 
*/ 

7 
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'HS'W 

•%*c , |l 

CNT, 

CMDNAMEV, 
KEYWORDV, 
KEYVALUEV); 
CMDNAME=CMDNAMEV; 
KEYWORD=KEYWORDV; 
KEYVALUE=KEYVALUEV; 
IF CNT=3 THEN 
CALL CNMSCOP(HLBPTR, 
CMDNAME, 
KEYWORD, 
KEYVALUE) ; 

ELSE 
H LBRC=CNM_BAD_I N VOCAT I ON ; 



/* Scan for the: 
/* ...command name 
/* ...skip over leading blanks 
..keyword up to "(" 
..skip over "(" 
..key value up to ")" 
..number strings parsed 
..command goes here 
..keyword goes here 
. .keyvalue goes in here 
Get fixed length value 
Get fixed length value 
Get fixed length value 
Enough parms specified? 
Scope check the input... 
...the command 
...the keyword 
...the value 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
I* 
/* 
/* 

r 
/* 
/* 



v 
v 

7 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 



/* Not enough parms specified */ 
/* Set re */ 



/******************•******************************************•*******/ 

/* Inform user of the return code results... */ 

/•••A******************************************************** 

SELECT; 
WHEN(HLBRC=CNM_GOOD) 
DO; /* Operator */ 

/* has */ 

/* passed */ 

END; /* scope checking */ 

WHEN (HLBRC=CNM_KEYWORD_NA) 
CALL CNMSMSG(HLBPTR,' Not authorized to use KEYWORD ' | (KEYWORD, 

'MSGVOPERV'); 
WHEN(HLBRC=CNM VALUE NA) 
CALL CNMSMSGTHLBPTR, ' Not authorized to use VALUE ' | IKEYVALUE, 
'MSGVOPERV); 
WHEN(HLBRC=CNM_BADJNV0CATION) 
CALL CNMSMSGTHLBPTR, ' Not enough parms specified 1 , 
•MSGVOPERV); 
OTHERWISE 
CALL CNMSMSG(HLBPTR, ' RC not recognized... ' | (HLBRC, 

•MSGVOPERV');- 
END; 

HLBRC=CNM_G00D; /* Clear RC */ 

END PSCOPCK; 



Appendix B. PL/I SamDles 9** 



Sample Command Processor for Sequential Logging 

This sample is an example of a command processor to log text to a sequential log. 
PSEQLOG: PROC(HLBPTR,CMDBUF,ORIGBLCK) OPTIONS (MAIN, REENTRANT); 

/* V 

/* (C) COPYRIGHT IBM CORP. 1989 */ 

/* V 

/* IEBCOPY SELECT MEMBER=((CNMS4219, PSEQLOG, R)) */ 

/* V 

/* Descriptive Name: High Level Language PL/I Sequential */ 

/* Logging Example */ 

/* V 

/* Function: */ 

/* V 

/* Write the text passed to this command procedure via the */ 

/* command line to the log. */ 

/* */ 

/* The syntax of this command is: */ 

/* V 

/* PSEQLOG LOGTEXT */ 

/* */ 

/* Dependencies: NONE */ 

/* */ 

/* Restrictions: NONE */ 

/* 7 

/* Language:: PL/I */ 

/* V 

/* Installation: */ 

/* V 

/* (1) ASSEMBLE AND LINKEDIT THIS MODULE AM0DE=31,RM0DE=ANY */ 

/* TYPE=RENT */ 

/* (2) ALLOC PRIMARY AND SECONDARY SEQUENTIAL DATA SET */ 

/* (3) USE DD NAMES IN NETVIEW PROC OR THE ALLOCATE COMMAND */ 

/* TO ALLOCATE THE DATA SETS TO NETVIEW. */ 

/* ALLOCATE THE DATA SETS AS */ 

/* SQLOGP & SQLOGS */ 

/* (4) ADD THE FOLLOWING STATEMENT TO DSIDMN */ 

/* TASK M0D=DSIZDST,TSKID=SQL0GTSK,MEM=SQL0GMEM,PRI=3,INIT=Y*/ 

/* (5) ADD THE FOLLOWING MEMBER (SQLOGMEM) TO DSIPARM */ 

/* DSTINIT FUNCT=0THER,DSRB0=1 */ 

/* DSTINIT PBSDN=SQL0GP */ 

/* DSTINIT SBSDN=SQLOGS */ 

/* LOGINIT AUTOFLIP=YES,RESUME=NO */ 

/* (6) ADD THE FOLLOWING CMDMDL TO DSICMD */ 

/* PSEQLOG CMDMDL MOD=PSEQLOG,TYPE=R,RES=N */ 

/* V 
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/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



Input: 
1) 
2) 

3) 



4-byte pointer to the HLB control block 
varying length character string of command (or message 
for user exits) that invoked this procedure 
40-byte parameter list which describes the origin of 
the request that caused execution of this procedure. 



Output: 

Writes input to a sequential log 

Return Codes: returned in HLBRC 
= normal exit 
-5 = canceled 

External Module References: None 

Change Activity: 

date, author: description of changes 



7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
V 
V 
7 
7 



/* 7 

/•A******************************************************************/ 



DCL HLBPTR PTR; 

%INCLUDE DSIPLI; 

DCL CMDBUF CHAR(*) VARYING; 

DCL ORIGBLCK CHAR(40); 

DCL ORIGIN PTR; 

ORIGIN=ADDR(ORIGBLCK); 



/* 
/* 
/* 
/* 
/* 
/* 



Pointer to the HLB 
Include the HLL macros 
Buffer for the command 
Area for the Orig Block 
Pointer to the Orig Block 
Address the Orig Block 



7 
7 
7 
7 
7 
7 



/* 7 

/* Customization starts here */ 

/* 7 

/it*************************************************************** 

/••••••••••••••A***************************************************** 

/* 7 

/* Declares */ 

/* 7 

y********************************************************** **********/ 

7 
7 
7 
7 
7 
7 
7 
7 
7 
7 
7 



DCL logtask 
INIT 
DCL domain 
DCL logtime 
DCL opid 
DCL logtext 
DCL loghdr 
DCL logbfr 
DCL errmsg 
DCL re 
del parment 



CHAR(8) 
('SQLOGTSK'); 
CHAR(8) var; 
CHAR(8) var; 
CHAR(8) var; 
CHAR (229) var; 
CHAR(27) INIT((27) ' 
CHAR(256) var; 
CHAR (80) var; 
CHAR(16) var; 
fixed bin(31); 



/* 
/* 
/* 
/* 
/* 
/* 
'); /' 



Sequential log task id - 
specified in DSIDMN 

Domain name 

Time 

Operator name 

Holds text to be logged 
Holds some header info 



/* Holds the buffer to be logged 
/* Holds error message 
/* Character form of return code 
/* Number of elemets parsed 
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/********************************************************************/ 

/* */ 

/* Execution */ 

/* V 

/•••••♦A*************************************************************/ 



CNMSSCAN DATA(cmdbuf) 

FORMAT ('%*S%*C%H') 



%*S 

%*c 



/* Scan the input 

/* skipping the cmd name 

/* and the following blank 

/* the remainder is the text 

/* to be logged %{-•} 

/* number of elements scanned 

/* scan text into logtext 

/* Get the domain name 

/* and the time 

/* and the operator id 



V 
V 
V 
V 
V 
V 
V 



COUNT (parmcnt) 
PI (logtext); 

CNMINFOC ITEMC DOMAIN') 

DATA (domain) LENG(8); 
CNMINFOC ITEMC TIME') 

DATA(logtime) LENG(8); 
CNMINFOC ITEM('OPID') 

DATA(opid) LENG(8); 

substr(loghdr,l) = domain; 
substr(loghdr,10) = logtime; 
substr(loghdr,19) = opid; 

logbfr = loghdr || logtext; 

CNMSENDMSG DATA (logbfr) 
MSGTYPE('MSG') 
DESTTYPE('SEQLOG') 

DEST(logtask); 

/A*******************************************************************/ 

/* Inform user of the return code results... */ 



/* Put domain name in header 
/* ditto for time 
/* and opid 

/* Concat header and text 



V 

V 

*/ 
*/ 
*/ 

V 



/* Text is in logbfr 

/* message type is 'MSG' 

/* destination is sequential log */ 

/* name of task is in logtask */ 



V 
V 



/ 



******************************************************************* 



if hlbrc -«= then do; 
re = char (hlbrc); 
errmsg = 'SL0G000 ERROR, RC from SENDMSG = 

substr(rc,length(rc)-4); 
CNMSENDMSG DATA(errmsg) MSGTYPE('MSG*) 

DESTTYPE('TASK') DEST(origin->orig_task); 
end; 



/ 



END PSEQLOG; 
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Appendix C. C Control Blocks and Include Files 

This appendix describes the c Control Blocks and Include files needed to write in c. 



DSIC 



/••A**************************************************************** 

/* */ 

/* NAME = DSIC */ 

/* V 

/* DESCRIPTIVE NAME = Main HLL C Include File */ 

/* V 

/* 5665-362 for MVS/XA */ 

/* THIS PRODUCT CONTAINS */ 

/* "RESTRICTED MATERIAL OF IBM" */ 

/* (c) COPYRIGHT IBM CORP 1989 */ 

/* ALL RIGHTS RESERVED */ 

/* LICENSED MATERIALS-PROPERTY OF IBM */ 

/* REFER TO COPYRIGHT INSTRUCTION FORM */ 

/* NUMBER G120-2083 */ 

/* 7 

/*. STATUS = NetView Release 3 */ 

/* */ 

/* FUNCTION = DSIC is required and must be included by all HLL */ 

/* programs written in C. DSIC includes all of the external */ 

/* HLL control blocks and include files needed to run C */ 

/* programs in the NetView environment. */ 

/* */ 

/* NOTES = see below */ 

/* V 

/* DEPENDENCIES = none */ 

/* */ 

/* RESTRICTIONS = none */ 

/* */ 

/* REGISTER CONVENTIONS = not applicable */ 

/* V 

/* PATCH LABEL = not applicable */ 

/* V 

/* MODULE TYPE = include file */ 

/* V 

/* PROCESSOR = C */ 

/* */ 

/* EXTERNAL REFERENCES = none */ 

/* */ 

/* CHANGE ACTIVITY */ 

/* V 

/••A********************************************************* 

#include "dsiccons.h" /* Constants */ 
#include "dsicvarc.h" /* Varying length char structure */ 

#include "dsichlb.h" /* Mapping of HLB */ 

#include "dsicorig.h" /* Mapping of Origin block '*/ 

#include "dsiccall.h" /* HLL function definitions */ 

#include "dsiccnm.h" /* HLL return code constants */ 
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DSICCONS 



/* 7 

/* NAME = DSICCONS */ 

/* 7 

/* DESCRIPTIVE NAME = HLL C Constants */ 

/* 7 

/* 5665-362 for MVS/XA */ 

/* THIS PRODUCT CONTAINS */ 

/* "RESTRICTED MATERIAL OF IBM" */ 

/* (c) COPYRIGHT IBM CORP 1989 */ 

/* ALL RIGHTS RESERVED */ 

/* LICENSED MATERIALS-PROPERTY OF IBM */ 

/* REFER TO COPYRIGHT INSTRUCTION FORM */ 

/* NUMBER G120-2083 */ 

/* 7 

/* STATUS = NetView Release 3 */ 

/* 7 

/* FUNCTION = This file contains the definitions for constants */ 

/* that are helpful when coding HLL modules in C. */ 

/* 7 

/* NOTES = see below */ 

/* 7 

/* DEPENDENCIES = none */ 

/* 7 

/* RESTRICTIONS = none */ 

/* 7 

/* REGISTER CONVENTIONS = not applicable */ 

/* 7 

/* PATCH LABEL = not applicable */ 

/* 7 

/* MODULE TYPE - constants */ 

/* 7 

/* PROCESSOR = C */ 

/* 7 

/* EXTERNAL REFERENCES = none */ 

/* 7 

/* CHANGE ACTIVITY */ 

/* 7 

/A************************************************************ 

/* Constants common across HLL services */ 

/A***************************************************** 

OxOO 



#define ZERO 




#define TRAPQ 


1 


#define OPERQ 


2 


#define DATAQ 


3 


#define IDATAQ 


4 


fdefine CNMIQ 


5 
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/********************************************************************/ 

/* Constants for calls to Cnmaltd */ 

/********************************************************************/ 

#define INSLINE "INSLINE " 
#define REPLINE "REPLINE " 
#define DELLINE "DELLINE " 

/********************************************************************/ 

/* Constants for Cnmcpys */ 

/••••••••••••A*******************************************************/ 

#define FIXTOFIX "FIXTOFIX" 

#define FIXTOVAR "FIXTOVAR" 

#define VARTOFIX "VARTOFIX" 

#define VARTOVAR "VARTOVAR" 



******************************************************************* 



/ 

/* Constants for calls to Cnmgetd 



/ 



******************************************************************* , 



/ 

#define GETMSG 
#define GETLINE 
#define PEEKLINE 
#define FLUSH LIN 
#define FLUSHMSG 
#define FLUSHQ 



"GETMSG 

"GETLINE 

"PEEKLINE 

"FLUSHLIN 

"FLUSHMSG 

"FLUSHQ 



/*******************************************************************/ 

/* Constants for Cnmcnmi */ 

/••••••A************************************************************/ 

#define SENDRESP "SENDRESP" 
#define SENDRPLY "SENDRPLY" 

/********************************************************************/ 
/* Constants for Cnmlock */ 



/ 



******************************************************************** 



/ 



#define UNLOCK 


"UNLOCK " 


#define LOCK 


"LOCK 


#define TEST 


"TEST 


#define WAIT 


"WAIT 


#define NOWAIT 


"NOWAIT " 



******************************************************************** , 



/ 

/* Constants for Cnmnams, Cnmpool and Cnmcell 



******************************************************************** , 



/ 

#define ALLOC 
#define FREE 
#define LOCATE 
#define REALLOC 



"ALLOC 
"FREE 
"LOCATE 
"REALLOC 
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#define RESIDENT 
Idefine ST0RAG31 1 
#define ST0RAG24 2 



********************************************************************, 



/ 

/* Constants for Cnmsmsg 



******************************************************************* 



/ 

#define 

#define 

Idefine 

#define 

#define 

#define 

#define 

#define 

#define 

#define 

#define 

Idefine 

Idefine 

Idefine 

Idefine 

Idefine 

Idefine 

Idefine 



MSG 

MSG C 

MSG L 

MSG_D 

MSG_E 

MSG F 

COMMAND 

REQUEST 

DATA 

OPER 

TASK 

SYSOP 

NETVLOG 

EXTLOG 

SEQLOG 

AUTHRCV 

OPCLASS 

NULLCHAR 



"MSG 

"MSG C 

"MSG~L 

"MSG D 

"MSGJ 

"MSG_F 
"COMMAND 
"REQUEST 
"DATA 
"OPER 
"TASK 
"SYSOP 
"NETVLOG 
"EXTLOG 
"SEQLOG 
"AUTHRCV 
"OPCLASS 



/********************************************************************/ 

/* Constants for Cnmvars */ 

/•••♦A***************************************************************/ 



Idefine PUT 


"PUT 


it 


Idefine DCL 


"DCL 


it 


Idefine GET 


"GET 


ii 


Idefine LOCAL 


"LOCAL 


ii 


Idefine TGLOBAL 


"TGLOBAL 


ii 


Idefine CGLOBAL 


"CGLOBAL 


ii 


Idefine CALLER 


"CALLER 


ii 



********************************************************************, 



/ 

/* Constants for Cnmkio 



/•A******************************************************************, 

Idefine GET_EQ "GETJQ " 

Idefine GET_EH "GET~EH " 

Idefine GETJEXT "GET'nEXT" 

Idefine GET PREV "GET~PREV U 
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#define ERASE "ERASE 

#define ENDREQ "ENDREQ 

#define UPDATE "UPDATE 

#define NOUPDATE "NOUPDATE 

#define DIRECT "DIRECT 

/••♦A********************************************* 

/* Constants for user exits running under a DST */ 

/********************************************************************/ 

#define USERASIS G 

#define USERDROP 4 

#define USERSWAP 8 

#define USERLOG 12 

#define USERLOGR 16 

#define USERHCL 20 

#define USERHCLR 24 

#define USERDINT 233 

#define USERVINT 234 

#define USERVINP 235 

#define USERVOUT 236 

#define USERCINP 237 

#define USERCOUT 238 

#define USERXLOG 240 

#define USERBINT 241 

#define USERBOUT 242 

/**************************************************************** 

/* Constants for Cnmvlc and Cnmnvlc */ 

/******************************************^ 

#define NOHEXCNV 

#define CNVTOHEX 1 
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DSICVARC 



/* V 

/* NAME = DSICVARC */ 

/* V 

/* DESCRIPTIVE NAME = HLL C Varying Length Character Stings */ 

/* V 

/* 5665-362 for MVS/XA */ 

/* THIS PRODUCT CONTAINS */ 

/* "RESTRICTED MATERIAL OF IBM" */ 

/* (c) COPYRIGHT IBM CORP 1989 */ 

/* ALL RIGHTS RESERVED */ 

/* LICENSED MATERIALS-PROPERTY OF IBM */ 

/* REFER TO COPYRIGHT INSTRUCTION FORM */ 

/* NUMBER G120-2083 */ 

/* V 

/* STATUS = NetView Release 3 */ 

/* */ 

/* FUNCTION = DSIVARCH is a structure type which represents */ 

/* varying length character strings for use in NetView High */ 

/* Level Language service routine invocations. */ 

/* V 

/* The structure consists of two parts: */ 

/* short int size - A 2 byte field which holds the size of */ 

/* the character string. The end of string */ 

/* character (\0) is not included in this */ 

/* size but MUST delimit the character */ 

/* string. */ 

/* */ 

/* char *buffer - A character string delimited by the end */ 

/* of string character (\0). */ 

/* */ 

/* NOTES = see below */ 

/* */ 

/* DEPENDENCIES = none */ 

/* */ 

/* RESTRICTIONS = none */ 

/* */ 

/* REGISTER CONVENTIONS = not applicable */ 

/* */ 

/* PATCH LABEL = not applicable */ 

/* V 

/* MODULE TYPE = structure map */ 

/* */ 

/* PROCESSOR = C */ 

/* */ 

/* EXTERNAL REFERENCES = none */ 

/* V 

/* CHANGE ACTIVITY */ 

/* V 

typedef struct { 

short int size; /* Length of buffer */ 

char buffer?? (256??); /* Varying length buffer */ 
} Dsivarch; 
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DSICHLB 



/* V 

/* NAME * DSICHLB */ 

/* */ 

/* DESCRIPTIVE NAME = HLL C Mapping of DSIHLB */ 

/* V 

/* 5665-362 for MVS/XA */ 

/* THIS PRODUCT CONTAINS */ 

/* "RESTRICTED MATERIAL OF IBM" */ 

/* (c) COPYRIGHT IBM CORP 1989 */ 

/* ALL RIGHTS RESERVED */ 

/* LICENSED MATERIALS-PROPERTY OF IBM */ 

/* REFER TO COPYRIGHT INSTRUCTION FORM */ 

/* NUMBER G120-2083 */ 

/* V 

/* STATUS = NetView Release 3 */ 

/* */ 

/* FUNCTION = This file contains a C mapping of DSIHLB, an */ 

/* internal control block. */ 

/* */ 

/* NOTES = see below */ 

/* V 

/* DEPENDENCIES = none */ 

/* */ 

/* RESTRICTIONS - none */ 

/* */ 

/* REGISTER CONVENTIONS - not applicable */ 

/* V 

/* PATCH LABEL = not applicable */ 

/* */ 

/* MODULE TYPE = structure map */ 

/* */ 

/* PROCESSOR = C */ 

/* V 

/* EXTERNAL REFERENCES = none */ 

/* V 

/* CHANGE ACTIVITY */ 

/* V 
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typedef struct { 



int 


Hlblen; 


int 


*Hlbwka; 


int 


♦Hlbhlls; 


int 


*Hlbtib; 


int 


*Hlbuser; 


int 


Hlbrc; 


int 


Hlbleng; 



unsigned int Hlbsense; 
unsigned int Hlbrsrv; 
char Hlbffdca??(48??); 
} Dsihlb; 



/* 
/* 
/* 
/* 
/* 
/* 
/* 



/* 
/* 
/* 



Length of HLB */ 

Pointer to WKA for API modules*/ 
Pointer to HLLS (-■ used by C) */ 
Pointer to TIB */ 

User word */ 

Return code from last API call*/ 
Length of data returned if 
Hlbrc = 0. Otherwise, length 
of data that would have been 
returned if truncation had 
not occurred. 
Sense code from CNMI 
Reserved 
First failure data capture 



*/ 

V 



V 

*/ 
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DSICORIG 



/* V 

/* NAME = DSICORIG */ 

/* V 

/* DESCRIPTIVE NAME = HLL C Origin Block Mapping */ 

/* */ 

/* 5665-362 for MVS/XA */ 

/* THIS PRODUCT CONTAINS */ 

/* "RESTRICTED MATERIAL OF IBM" */ 

/* (c) COPYRIGHT IBM CORP 1989 */ 

/* ALL RIGHTS RESERVED */ 

/* LICENSED MATERIALS-PROPERTY OF IBM */ 

/* REFER TO COPYRIGHT INSTRUCTION FORM */ 

/* NUMBER G120-2083 */ 

/* V 

/* STATUS = NetView Release 3 */ 

/* */ 
/* FUNCTION = This file defines the mapping of the origin block */ 

/* of the request that caused the execution of the procedure */ 

/* currently running. */ 

/* V 

/* NOTES = see below */ 

/* V 

/* DEPENDENCIES = none */ 

/* */ 

/* RESTRICTIONS = none */ 

/* V 

/* REGISTER CONVENTIONS = not applicable */ 

/* */ 

/* PATCH LABEL = not applicable */ 

/* V 

/* MODULE TYPE = structure map */ 

/* V 

/* PROCESSOR = C */ 

/* */ 

/* EXTERNAL REFERENCES = none */ 

/* */ 

/* CHANGE ACTIVITY */ 

/* V 

/********************************************************************/ 

typedef struct { 
int Orig_block_length; 

char 0rig_dummyl??(8??); /* Reserved */ 

char 0rig__domain??(8??); /* Origin domain id */ 

char 0rig~task??(8??); /* Origin task id */ 

char 0rig_process??(8??); 

char Orig_msg_type; /* Message type from HDRMTYPE */ 

char Orig_line_type; /* Line type */ 

char Orig_dummy2??(2??); /* Reserved */ 

} Dsiorig; 
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DSICCALL 



/* V 

/* NAME - DSICCALL */ 

/* V 

/* DESCRIPTIVE NAME - HLL C Service Routine Definitions */ 

/* V 

/* 5665-362 for MVS/XA */ 

/* THIS PRODUCT CONTAINS */ 

/* "RESTRICTED MATERIAL OF IBM" */ 

/* (c) COPYRIGHT IBM CORP 1989 */ 

/* ALL RIGHTS RESERVED */ 

/* LICENSED MATERIALS-PROPERTY OF IBM */ 

/* REFER TO COPYRIGHT INSTRUCTION FORM */ 

/* NUMBER G120-2083 */ 

/* V 

/* STATUS = NetView Release 3 */ 

/* V 

/* FUNCTION ■ This files defines the following service routines */ 

/* for C: */ 

/* 1. Preprocessor directives */ 

/* 2. Function declarations */ 

/* 3. Macro definitions */ 

/* V 

/* NOTES = see below */ 

/* V 

/* DEPENDENCIES = none */ 

/* V 

/* RESTRICTIONS = none */ 

/* V 

/* REGISTER CONVENTIONS = not applicable */ 

/* */ 

/* PATCH LABEL = not applicable */ 

/* V 

/* MODULE TYPE = structure map */ 

/* V 

/* PROCESSOR - C */ 

/* */ 

/* EXTERNAL REFERENCES = none */ 

/* */ 

/* CHANGE ACTIVITY */ 

/* */ 

y*************************************************^ 
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/* Preprocessor directives */ 

/* Each of the HLL service routines uses OS linkage. */ 

/••A*****************************************************************/ 

#pragma linkage(Cnmaltd, OS) 

Ipragma linkage(Cnmcell, OS) 

#pragma linkage(Cnmcmd, OS) 

#pragma linkage(Cnmcnmi, OS) 

#pragma linkage(Cnmcpys, OS) 

#pragma linkage(Cnmgeta, OS) 

#pragma linkage(Cnmgetd, OS) 

#pragma linkage(Cnminfc, OS) 

#pragma linkage(Cnminfi, OS) 

#pragma linkage(Cnmkio, OS) 

#pragma linkage(Cnmlk, OS) 

#pragma linkage(Cnmmemo, OS) 

#pragma linkage(Cnmmemr, OS) 

#pragma linkage(Cnmmemc, OS) 

#pragma linkage(Cnmnams, OS) 

#pragma linkage(Cnmpool, OS) 

#pragma linkage(Cnmscop, OS) 

#pragma linkage(Cnmsmsg, OS) 

Ipragma linkage(Cnmvars, OS) 



/***************************•****************************************/ 

/* Function declarations */ 

/* Each of the HLL service routines has a function declaration */ 
/* defining its parameter list. */ 

void Cnmaltd(Dsihlb **hlbptr, char *adfunc, void *adbuf, 

void *adorigin, int adqueue, int adindex); 
void Cnmcell (Dsihlb **hlbptr 4 char *pcfunc, int pctoken, 

void *pcstrptr); 
void Cnmcmd (Dsihlb **hlbptr, void *cmdstr); 
void Cnmcnmi (Dsihlb **hlbptr, char *cnfunc, void *cndata, 

char *cndest, int cntimout); 
void Cnmcpys (Dsihlb **hlbptr, void *csfrom, void 

char *cstype); 
void Cnmgeta (Dsihlb **hlbptr, char *ganame, void 

int gadatlen, int gaqueue); 
void Cnmgetd (Dsihlb **hlbptr, char *gdfunc, void 

int gdbuflen, void *gdorigin, int gdqueue, int gdindex); 
void Cnminfc (Dsihlb **hlbptr, char *icname, void *icdata, 

int icdatlen); 
void Cnminfi (Dsihlb **hlbptr, char *iiname, int *iinumb); 
void Cnmkio(Dsihlb **hlbptr, char *vsfunc, void *vsdata, 

int vsdatlen, void *vskey, char *vsoption); 
void Cnmlk (Dsihlb **hlbptr, char *lkfunc, void *lkname, 

char *lkscope, char *lkoption); 
void Cnmmemo( Dsihlb **hlbptr, int *motoken, char *moddname, 

char *momemnam) ; 



^csto, int cslen, 

^gadata, 

^gdbuf, 
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void Cnnrnemr(Dsih1b **hlbptr, int mrtoken, void *mrdata, int mrdatlen); 

void Cnmmemc(Dsihlb **hlbptr, int mctoken); 

void Cnmnams(Dsih1b **hlbptr, char *nsfunc, void *nsptr, 

void *nsname, int *nsleng, int nsclass); 
void Cnmpool(Dsihlb **hlbptr, char *spfunc, int *sptoken, void *spname, 

int spleng, int sppricnt, int spseccnt, int spclass); 
void Cnmscop(Dsihlb **hlbptr, char *sccmd, char *sckwd, char *scvalue); 
void Cnmsmsg(Dsihlb **hlbptr, void *smtext, char *smmsgtype, 

char *smdestyp, char *smdestid); 
void Cnmvars(Dsihlb **hlbptr, char *cvfunc, void *cvdata, 

int cvdatlen, void *cvname, char *cvpool); 

/•A***************************************************** 

/* Function declarations */ 

/* Functions provided for use with varying length character */ 

/* strings. */ 

/if********************************************************* 

void *Cnmvlc(void *vstring, short convert, char *istring, ...); 

void *Cnmnvlc(void *vstring, short convert, int length, char *istring); 

/••••••••A************************************************** 

/* Macro definitions */ 

/* Each of the HLL service routines has a macro definition which */ 

/* inserts the hlb pointer (&Hlbptr) into the parameter list. */ 
/♦•••A******************************************* 

#define Cnmaltd(adfunc,adbuf,adorigin,adqueue,adindex) \ 
Cnmaltd(&Hlbptr,adfunc,adbuf,adorigin,adqueue,adindex) 

#define Cnmcell(pcfunc,pctoken,pcstrptr) \ 

Cnmcell(&Hlbptr,pcfunc,pctoken,pcstrptr) 

#define Cnmcmd(cmdstr) \ 

Cnmcmd (&H1 bptr, cmdstr) 

#define Cnmcnmi(cnfunc,cndata,cndest,cntimout) \ 

Cnmcnmi(&Hlbptr,cnfunc,cndata,cndest,cntimout) 

#define Cnmcpys(csfrom,csto,cslen,cstype) \ 

Cnmcpys(&Hlbptr,csfrom,csto,cslen,cstype) 

#define Cnmgeta(ganame,gadata,gadatlen,gaqueue) \ 

Cnmgeta(&Hlbptr,ganame,gadata,gadatlen,gaqueue) 

#define Cnmgetd(gdfunc,gdbuf,gdbuflen,gdorigin, \ 

gdqueue,gdindex) \ 

Cnmgetd(&Hlbptr,gdfunc,gdbuf,gdbuflen,gdorigin, \ 
gdqueue,gdindex) 

#define Cnminfc(icname,icdata,icdatlen) \ 

Cnmi nf c (&H1 bptr , i cname, i cdata, i cdatl en) 
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#define Cnmi nfi(ii name, ii numb) \ 

Cnml nf i (&H1 bptr , i i name , i i numb) 

#define Cnmkio(vsfunc,vsdata,vsdatlen,vskey,vsoption) \ 
Cnmkio(&H1bptr,vsfunc,vsdata,vsdatlen,vskey,vsoption) 

#define Cnmlk(1kfunc,lkname,lkscope,1koption) \ 

Cnml k(&H1 bptr, lkfunc,lkname,lkscope,lkopti on) 

#define Cnmmemo(motoken,moddname,momemnam) \ 

Cnmmemo(&Hlbptr,motoken,moddname,momemnam) 

#define Cnmmemr(mrtoken,mrdata,mrdatlen) \ 

Cnmmemr(&Hlbptr,mrtoken,mrdata,mrdatlen) 

#define Cnmmemc(mctoken) \ 

Cnmmemc (&H1 bptr,mctoken) 

#define Cnmnams(nsfunc,nsptr,nsname,nsleng,nsc1ass) \ 

Cnmnams(&Hl bptr, nsfunc,nsptr,nsname,ns!eng,nscl ass) 

#define Cnmpool(spfunc,sptoken,spname,sp1eng, \ 

sppricnt,spseccnt,spc1ass) \ 

Cnmpool (&H1bptr,spfunc,sptoken,spname,spleng, \ 
sppricnt,spseccnt,spclass) 

#define Cnmscop(sccmd,sckwd,scvalue) \ 

Cnmscop(&Hlbptr,sccmd,sckwd,scva1ue) 

#define Cnmsmsg(smtext,smmsgtype,smdestyp,smdestid) \ 

Cnmsmsg(&Hlbptr,smtext,smmsgtype,smdestyp,smdestid) 

#define Cnmvars(cvfunc,cvdata,cvdatlen,cvname,cvpool) \ 
Cnmvars(&H1bptr,cvfunc,cvdata,cvdatlen,cvname,cvpool) 
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DSICCNM 



/••••••A********************************************************** 

/* V 

/* NAME = DSICCNM */ 

/* */ 

/* DESCRIPTIVE NAME = HLL C Return Codes */ 

/* V 

/* 5665-362 for MVS/XA */ 

/* THIS PRODUCT CONTAINS */ 

/* "RESTRICTED MATERIAL OF IBM" */ 

/* (c) COPYRIGHT IBM CORP 1989 */ 

/* ALL RIGHTS RESERVED */ 

/* LICENSED MATERIALS-PROPERTY OF IBM */ 

/* REFER TO COPYRIGHT INSTRUCTION FORM */ 

/* NUMBER G120-2083 */ 

/* V 

/*■ STATUS = NetView Release 3 */ 

/* V 

/* FUNCTION = This file defines the HLL return codes for C. */ 

/* */ 

/* NOTES = see below */ 

/* */ 

/* DEPENDENCIES = none */ 

/* */ 

/* RESTRICTIONS = none */ 

/* */ 

/* REGISTER CONVENTIONS = not applicable */ 

/* */ 

/* PATCH LABEL = not applicable */ 

/* */ 

/* MODULE TYPE = constants */ 

/* */ 

/* PROCESSOR = C */ 

/* V 

/* EXTERNAL REFERENCES = none */ 

/* */ 

/* CHANGE ACTIVITY */ 

/* V 
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#define CNM_GOOD 

#define CNM BADJNVOCATION 4 

#define CNM~TOO"~MANY 8 

#define CNM""BAD~SYNTAX 12 

#define CNM~BAD~DDNAME 16 

Idefine CNM~NOT~FOUND 20 

#define CNM NOJTORAGE ,24 

#define CNM IOERROR 28 

#define CNM _ BAD TOKEN 32 

#define CNMJNDJILE 36 

Idefine CNM~DATA TRUNC 40 

Idefine CNM"NOT IN ASYNC 44 

#define CNM~BAD~RULENG 48 

#define CNM~BAD FUNC 52 

#define CNM~BADJ1ME0UT 56 

#define CNMJEED PRID 60 

#define CNM NEG_RESPONSE 64 

#define CNM~TIME OUT 68 

#define CNM~BAD_QUEUE 72 

Idefine CNM BAD INDEX 76 

#define CNM~QUEUE EMPTY 80 

#define CNM~BAD ORIGBLOCK 84 

Idefine CNM~BAD~LENGTH 88 

#define CNM JOT MLWTO 92 

#define CNM BAD*"LINETYPE 96 

Idefine CNM~NOCUR LINE 100 

Idefine CNM~DUPL NAME 104 

Idefine CNM~BAD_NAME 108 

Idefine CNM_BAD_CLASS 112 

Idefine CNM_BAD MSGTYP 116 

Idefine CNM_BAD~DESTYP 120 

Idefine CNM TYP~CONFLICT 124 

Idefine CNM~BAD~0PTI0N 128 

Idefine CNM~COMMAND NA 132 

Idefine CNM~KEYW0RDJA 136 

Idefine CNMJALUE NA 140 

Idefine CNM BAD COMMAND 144 

Idefine CNM~BAD~KEYWORD 148 

Idefine CNM NOJRAP 152 

Idefine CNM BAD_POOL 156 

Idefine CNM~BAD_ADDR 160 

Idefine CNM~BAD_TASKNAME 164 

Idefine CNM~BAD MODNAME 168 

Idefine CNM~~BADJD 172 

Idefine CNMJAD COMBO 176 

Idefine CNM TVB INUSE 180 

Idefine CNM~RID~INUSE 184 
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#define 


CNM RID SELF 


188 


#define 


CNM BAD PRI COUNT 


192 


#define 


CNM~BAD SEC COUNT 


196 


#define 


CNM~DUPL KEY 


200 


#define 


CNM NOT IN POOL 


204 


#def i ne 


cnm~locked 


208 


#define 


CNM LOCK INUSE 


212 


#define 


CNM~LOG INACTIVE 


216 


#define 


cnm"~task INACTIVE 


220 


#define 


CNM TIME OUT WAIT 


224 


#define 


CNM~GO ON WAIT 


228 


#define 


CNM MSG ON WAIT 


232 


#define 


CNM OPINPUT ON WAIT 


236 


#define 


CNM DATA ON WAIT 


240 


#define 


CNM NO TRAP~SET 


244 


#define 


CNM~NO PREV~WAIT 


248 


#define 


cnm"bad cstype 


252 


#define 


CNM~BAD CELL ADDRESS 


256 


#define 


cnmj:ell_already_free 


260 


#define 


CNM BAD MQS 


1000 


#define 


CNM~DST FAILURE 


2000 


Idefine 


CNM~BAD EXCMS 


3000 


#define 


CNM BAD PUSH 


4000 


#define 


CNM~BAD POP 


5000 


#define 


CNM BAD WLS 


6000 


#def i ne 


CNM BAD PSS 


7000 


#define 


CNMJAD_WTO 


8000 


#define 


CNM~BAD CES 


9000 


#define 


cnm~bad~dks 


10000 


#define 


cnm~bad~kvs 


11000 


#define 


CNM BAD~LOAD 


12000 


#define 


CNM BAD LCS 


13000 


#define 


CNM BAD CDS 


14000 


#define 


CNM BAD ESTAE 


15000 


#define 


CNM BAD PAS 


16000 


#define 


CNM_BAD~SNTXS 


17000 


#def i ne 


CNM_BAD_MRBLD 


18000 


#define 


CNM BAD ZCSMS 


20000 


#define 


CNM BAD ENQ 


21000 



#define CNM BAD ZVSMS 100 
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Appendix D. C Samples 



This appendix contains a table of the c samples that are shipped with NetView in 
sysi.cnmsamp. When data set names are referred to in this appendix, two names 
are given, such as ctmpplt (CNMS4201). The first name is the alias name, and the 
name in parenthesis is in the NetView samples library. You can use either name to 
access the samples, dsicmd has definitions for the alias names to allow those 
names to be entered as commands. 

The following steps allow you to enter the member names as commands: 

1. Compile and link edit the samples using the alias name. 

2. Delete the (*) in column one of the appropriate cmdmdl statement in dsicmd to 
be able to execute the alais name as a command. No entries are needed in 
dsicmd for user exits. 

3. NetView must be recycled to pick up the dsicmd changes. 

Notes: 

1. See the prologues of the samples for information about how certain samples 
are related and special cases for user exit routines. 

2. Each alias name for c begins with the letter c. 

This appendix also contains a description of each sample, and coded samples of a 
user exit routine and two command processors. 



Appendix D. C Samples 295 



C Samples Table 



The following table refers to the c samples that are shipped with NetView. The 
table contains the function, the alias name, and the name of the member in 

SYS1.CNMSAMP. 



Sample function 



Template for commands and user exit routines 

Sample DSIEX03 to set a global variable 

Uses Cnmsmsg to send data 

Uses WAIT FOR DATA 

Sample DSIEXG2A changes a WTO to an MLWTO 

Uses Cnmcnmi to forward RUs to a PU 

Uses Cnmkio for I/O to VSAM 

HLL command using Cnmscop for scope checking 

Display full screen VIEW panel 

Activates LU and uses TRAP and WAIT to 

determine if activation is successful 

Uses Cnmsmsg to log text to a sequential log 

DST initialization exit for USERVSAM DST 

Primes VSAM empty data set for USERVSAM DST 

Sends a request to USERVSAM DST 

Processes VSAM requests under USERVSAM DST 

Primes VSAM empty data set for CKEYIO 



C s< 


imple 


Alias 


CNMSAMP 


CTMPPLT 


CNMS4201 


CEXIT3 


CNMS4240 


CSNDDAT 


CNMS4241 


CWATDAT 


CNMS4242 


CEXIT2A 


CNMS4243 


CCNMI 


CNMS4244 


CKEYIO 


CNMS4245 


CSCOPCK 


CNMS4246 


CFLVIEW 


CNMS4247 


CACTLU 


CNMS4248 


CSEQLOG 


CNMS4249 


CXITDI 


CNMS4250 


CXITVN 


CNMS4251 


CSNDDST 


CNMS4252 


CDOVSAM 


CNMS4253 


CPRIME 


CNMS4254 
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C Samples Description 



For each sample, a description of the function and the hll service routines utilized 
are given. 

CTMPPLT(CNMS4201) 

This sample is a template for commands and user exit routines in c. 

This sample is included in Chapter 9 on page 107 

CEXIT3 (CNMS4240) 

This is a sample dsiexo3 that sets a task global variable. This global variable will 
contain the value of the last time that a command other than csnddat was entered 
under an ost. cwatdat and csnddat are used to interrogate this value. 

The hll service routines utilized in this sample are: Cnminfc, Cnmvars. 

CSNDDAT (CNMS4241) 

This sample uses Cnmsmsg to send data. The sample is part of an example of 
sending messages with a type of request, waiting on the response, and parsing the 
results. 

The purpose of the example is to find the last time that a command was entered on 
a given ost. A task global variable is set by cexits every time a command is 
entered on an ost. cwatdat uses Cnmsmsg to issue a csnddat on the task in ques- 
tion, cwatdat then goes into a wait state, csnddat retrieves the value of the global 
variable and uses Cnmsmsg to send the data back to the task that issued the 
cwatdat. cwatdat breaks out of the wait state (it has received the data it was 
waiting for), and parses and displays the data. 

The hll service routines utilized in this sample are: Cnmvars, Cnmsmsg, Cnminfc. 

CWATDAT (CNMS4242) 

This sample uses wait for data. The sample is part of an example of sending mes- 
sages with a type of request, waiting on the response, and parsing the results. 

The purpose of the example is to find the last time that a command was entered on 
a given ost. A task global variable is set by cexit3 every time a command is 
entered on an ost. cwatdat uses Cnmsmsg to issue a csnddat on the task in ques- 
tion, cwatdat then goes into a wait state, csnddat retrieves the value of the global 
variable and uses Cnmsmsg to send the data back to the task that issued the 
cwatdat. cwatdat breaks out of the wait state (it has received the data it was 
waiting for), and parses and displays the data. 

The hll service routines utilized in this sample are: Cnmsmsg, Cnmcmd, Cnmgetd. 

CEXIT2A (CNMS4243) 

This sample exit converts a wro to an mltwo by adding two lines to the single-line 
wros that are driving the exit. 

The hll service routines utilized in this sample are: Cnmgetd, Cnmaltd. 

This sample is included in "Sample User Exit" on page 300. 
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CCNMI (CNMS4244) 

This sample uses Cnmcnmi to forward rus to a pu. NetView provides the Cnmcnmi 
service routine for use in communicating with devices in the network through the 
Communications Network Management Interface (cnmi). Any data that is returned 
may be accessed using the Cnmgetd service routine to retrieve records from the 
cnmi solicited data queue (cnmiq). 

This sample uses the Cnmcnmi service routine to send a product set id data 
request to a specified pu. Any data returned is sent as a message to the operator. 
The prologue of the sample contains instructions for set up. 

The hll service routines utilized in this sample are: Cnmcnmi, Cnmgetd, 
Cnmsmsg. 

CKEYIO (CNMS4245) 

This sample illustrates how to code a NetView hll command processor that allows 
i/o to a vsam file via the Cnmkio routine. It must execute on a dst. To run this 
command on a dst, either use the excmd command or the Cnmsmsg service routine 
(with a type of command). The prologue of the sample explains how to set up a dst. 

The hll service routines utilized in this sample are: Cnmkio, Cnmsmsg. 

CSCOPCK (CNMS4246) 

This sample illustrates the scope checking capabilities provided by NetView. This 
sample scope checks keywords and values of the cscopck command. In this 
sample, the user is required to set up the following elements for the command: 
operator id, operator classes that can access the command, and operator profile. 
See the prologue of the sample for more information. This command yields a 
message informing the operator if he is not authorized to use the keyword and 
value specified when invoking the command. 

The hll service routines utilized in this sample are: Cnmscop, Cnmsmsg. 

This sample is included in "Sample Command Processor for Scope Checking" on 
page 304. 

CFLVIEW (CNMS4247) 

This sample illustrates the usage of the full screen view command processor. 
The hll service routines utilized in this sample are: Cnmcmd, Cnmvars. 

CACTLU (CNMS4248) 

This sample illustrates how to issue a vtam command to activate an lu, trap the 
vtam messages that result, and respond depending on the messages received. 

The hll service routines utilized in this sample are: Cnmcmd, Cnmgetd, Cnmsmsg. 
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CSEQLOG (CNMS4249) 

This sample uses Cnmsmsg to log text to a sequential log. The prologue of the 
sample contains instructions for set up. 

The hll service routines utilized in this sample are: Cnminfc, Cnmsmsg. 

This sample is included in "Sample Command Processor for Sequential Logging" 
on page 309. 

CXITDI (CNMS4250) 

This sample is a dst initialization exit. The sample illustrates the dst initialization 
exit that is used by the uservsam dst. 

The hll service routines utilized in this sample are: Cnmvars, Cnmsmsg. 

CXITVN (CNMS4251) 

This sample primes a vsam empty data set for the uservsam dst. 

^SNDDST (CNMS4252) 

This sample sends a 'put' or 'get' request to the sample HLL Data Services 
Command Processor named cdovsam to store and retrieve a given value for a 
specified key (key and value limited to 11 characters in length). The sample also 
allows a specified NetView Command List Language variable (defined by the 
caller) to be set to the retrieved value. 

The hll service routines utilized in this sample are: Cnmsmsg, Cnmvars, Cnmgetd, 
Cnmcmd. 

)VSAM (CNMS4253) 

This sample is an hll Data Services Command Processor that runs under the 
sample Data Services Task (task ID 'uservsam'). It processes 'put' or 'get' 
requests sent by the csnddst sample, and will write or read an 11 character value 
associated with an 11 character key to the sample dst's vsam data set. The pro- 
logue of cdovsam contains instructions on installing the sample 'uservsam' Data 
Services Task. 

The hll service routines utilized in this sample are: Cnmsmsg, Cnmkio. 

E (CNMS4254) 

This sample primes a vsam empty data set for ckeyio. 
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C Coded Samples 

This section contains an example of a user exit routine and two command 
processors. 

Sample User Exit 

This sample is an example of user exit dsiexo2a. 

/* V 

/* (C) COPYRIGHT IBM CORP. 1989 */ 

./* V 

/* IEBCOPY SELECT MEMBER=((CNMS4243,CEXIT2A,R)) */ 

/* 7 

/* Descriptive Name: High Level Language C DSIEX02A Example */ 

/* V 

/* Function: */ 

/* V 

/* This DSIEX02A adds two lines to the single line WTOs */ 

/* that are driving the exit. */ 

/* V 

/* Introduction: */ 

/* V 

/* To convert a single line WTO into a multi-line WTO, */ 

/* you must change the line types accordingly: */ 

/* */ 

/* In Out */ 

/* — — */ 

/* msg_type = "E", msg_type="=" line_type="C" (Control) */ 

/* and a msg_type="=" line_type="D" (Data) */ 

/* line_type of " " msg_type="=" line_type="F" (Final) */ 

./* V 

/* Note: */ 

/* A Msg__type of "E" implies that the message was externally */ 

/* generated via a WTO. For example MVS D T would send */ 

/* a Msg_type of "E". The Msg_type of "=" implies a user */ 

/* generated MLWTO was issued. */ 

/* V 

/* Dependencies: None */ 

/* 7 

/* Restrictions: Only processes messages issued under */ 

/* mainline processing. */ 

/* V 

/* Language: C */ 

/* V 

/* Input: */ 

/* 1) 4-byte pointer to the HLB control block */ 

/* 2) varying length character string of command (or message */ 

/* for user exits) that invoked this procedure */ 

/* 3) 40-byte parameter list which describes the origin of */ 

/* the request that caused execution of this procedure. */ 

/* */ 
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/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/ 



Output: 

Messages to various tasks. 

Return Codes: returned in HLBRC 
= normal exit 

External Module References: None 

Change Activity: 

date, author: description of changes 



V 

V 

*/ 

7 
*/ 
V 
V 
V 
V 
V 
V 



****************************************************************** 



#pragma runopts (N0EXEC0PS,N0STAE,N0SPIE,ISASIZE(4K),ISAINC(4K)) 

/••••••♦♦♦•••A*******************************************************/ 

/* Standard include files 

/••A*****************************************************************/ 

#include <stdlib.h> /* Standard library */ 

#include <stdarg.h> /* Standard args */ 



/ 



******************************************************************** 



/ 



/* NetView high level language include files */ 

/********************************************************************/ 

#include "dsic.h" /* Include HLL macros */ 

/•••••••A************************************************************/ 

/* External data definitions */ 

/********************************************************************/ 

Dsihlb *Hlbptr; /* Pointer to the HLB */ 

Dsivarch *Cmdbuf; /* Pointer to command buffer */ 

Dsiorig *0rigblck; /* Pointer to Orig block */ 

main(int argc, char *argv??(??)) 

{ 

/••••••A***********************************************************/ 

/* Internal data definitions */ 

/••A***************************************************************/ 

Dsivarch datain, /* data returned by cnmgetd */ 

workbuf; /* replacemnt buf passed to cnmaltd*/ 



Dsiorig getblock; 



/* orig block 



7 
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/* Convert parameter pointers from character to hex addresses */ 

sscanf (argv??(l??),"%x\&Hlbptr); 
sscanf (argv?? (2??), "%x",&Cmdbuf); 
sscanf (argv?? (3?7) , "%x" ,&0ri gbl ck) ; 



/* Initialization */ 

/* */ 

/* Customization starts here ... */ 

/* V 

/••••A***************************************** 

/* */ 

/* Execution */ 

/* V 

Cnmgetd(PEEKLINE, /* ...function is get a message */ 



&datain, /* 

256, /* 

&getblock, /* 

IDATAQ, /* 

1); /* 



..result goes here */ 

..max input length */ 

..must provide a work area */ 
..get the first line of message*/ 
..get the first line of message*/ 



if (getblock.Orig_msg_type == 'E') /* WTO response to MVS command */ 
{ 

getblock.Orig_msg_type = '='; /* set msg type to MLWTO */ 

getblock.Orig_line_type = 'C; /* set line type to control */ 

datain.buffer??(datain.size??) = '\0'; /* append null to data */ 

/* ...retrieved by cnmgetd */ 

/* put replacement buffer in */ 
Cnmvlc(&workbuf, /* varying length character strng..*/ 

0, /* do not convert to hex */ 
"Change WTO to MLWTO, WT0= , %s'",datain. buffer); 
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/* 


replace the text... 


*/ 


Cnmaltd(REPLINE, 


/* 


...function is replace 


V 


fcworkbuf, 


/* 


...text of new message 


*/ 


&getblock, 


/* 


...use peeked Origin block 


V 


IDATAQ, 


/* 


...initial data queue 


V 


Ds 


/* 


...replace the first line 


V 



getblock.Orig__line_type = 'D'; /* set line type to data 



7 



/* put line to add to MLWTO in */ 

Cnmvlc(&workbuf, /* varying length character strng..*/ 

0, /* do not convert to hex */ 

"Add a data line to MLWTO"); /* line to add */ 



Cnmaltd(INSLINE, 


/* 


...function is insert 


V 


&workbuf, 


/* 


...text of new message 


V 


fcgetblock, 


/* 


...use peeked Origin block 


V 


IDATAQ, 


/* 


...initial data queue 


V 


2); 


/* 


...add a line 


V 



getblock.Orig_line_type = 'F';/* set line type to final line */ 

/* put line to add to MLWTO in */ 

Cnmvlc(&workbuf, /* varying length character strng..*/ 

0, /* do not convert to hex */ 

"Add an end of MLWTO message"); /* line to add */ 



Cnmalt 


d(INSLINE, 


/* 


...function is insert 


V 




&workbuf, 


/* 


...text of new message 


V 




&getblock, 


/* 


...use peeked Origin block 


V 




IDATAQ, 


/* 


...initial data queue 


*/ 




3); 


/* 


...add a line 


V 


} 
Hlbptr->Hlbrc == CNM GOOD; 

} 
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Sample Command Processor for Scope Checking 

This sample is an example of a command processor for scope checking. 

/••••a**************************************** 

/* 7 

/* (C) COPYRIGHT IBM CORP. 1989 */ 

/* */ 

/* IEBCOPY SELECT MEMBER=( (CNMS4246, CSCOPCK, R)) */ 

/*■ 7 

/* Descriptive Name: High Level Language C Scope Check */ 

/* Example */ 

/* 7 

/* Function: */ 

/* 7 

/* The following is an example of the scope checking capabilities */ 

/* provided by NetView. In this example, the user is required to */ 

/* set up the following elements for the command (shown below): */ 

/* (1) operator id */ 

/* (2) operator classes that can access the command */ 

/* (3) operator profile */ 

/* 7 

/* The command gives the return code that the scope check service */ 

/* routine returned to the operator. */ 

/* 7 

/* The syntax that this command checks for is: */ 

/* 7 

/* CSCOPCK PARMx(VALx) */ 

/* 7 

/* The following is the setup for the scope check example: */ 

/* 7 

/* In DSIPARM(DSICMD): 7 

/* Define the operator classes that can access */ 
/* the command, its keywords, and its keyword values.*/ 

/* 7 

/* The example below says that the command CSCOPCK */ 

/* can be executed by operators in scope class */ 

/* 1 and 2. Scope class 1 can issue any keyword */ 

/* or keyword value, but scope class 2 cannot use */ 

/* the value of VAL1 with keyword PARM2, and scope */ 

/* class 2 cannot issue PARM3 at all. */ 

/* 7 

/* Example: 7 

/* 7 

/* CSCOPCK CMDMDL MOD=CSCOPCK,RES=N,TYPE=RD */ 

/* CMDCLASS 1,2 */ 

/* PARM2 KEYCLASS 1,2 7 

/* VAL1 VALCLASS 1 */ 

/* PARM3 KEYCLASS 1 7 

/* VAL1 VALCLASS 1 */ 

/* 7 
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/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/*. 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



In DSIPARM(DSIOPF) 
Define the operator ids and the profiles that the operator 
ids can use. 



Example: 
JOE 



OPERATOR 
PROFILEN 



PASSWORD=USER 
DSIPROF3 



In DSIPRF(profilename) 
Define the operator class value that will correspond to the 
profile that the operator logs on with. 

Example: 
In the DSIPRF dataset, member name DSIPR0F3, 



DSIPR0F3 



PROFILE 
OPCLASS 3 
END 



Restrictions: None 



Language: C 



Input: 
1) 
2) 

3) 



4-byte pointer to the HLB control block 

varying length character string of command (or message 

for user exits) that invoked this procedure 

40-byte parameter list which describes the origin of 

the request that caused execution of this procedure. 



Output: 

Messages describing the scope of the operator. 

Return Codes: returned in HLBRC 
= normal exit 
-5 = cancelled 

External Module References: None 

Change Activity: 

date, author: description of changes 



V 

7 
7 
7 
7 
7 
7 
7 
7 
7 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 
V 



/it*******************************************************************, 

#pragma runopts (N0EXEC0PS,N0STAE,N0SPIE,ISASIZE(4K) ,ISAINC(4K)) 
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/* Standard include files 

/************************************************************* 

#include <string.h> /* String functions */ 

#include <stdlib.h> /* Standard library */ 

#include <stdarg.h> /* Standard args */ 

/•A********************************************************* 

/* NetView high level language include files */ 

/A************************************************************* 

linclude "dsic.h" /* Include HLL macros */ 

/•••A******************************************************** 

/* External data definitions */ 

/****************************************************************** 

Dsihlb *Hlbptr; /* Pointer to the HLB */ 

Dsivarch *Cmdbuf; /* Pointer to command buffer */ 

Dsiorig *0rigblck; /* Pointer to Origin block */ 



main(int argc, char *argv??(??)) 
{ 

/* Internal data definitions */ 

/•lit********************************************************* 

/* Buffer area for messages */ 

/* Ptr to cmd that invoked us */ 

/* Ptr to keyword of invocation*/ 

/* Ptr to key value of invocation*/ 

/* Ptr to keyvalue of invocation*/ 

";/* Command that invoked us */ 

";/* Keyword of invocation */ 

";/* Keyvalue of invocation */ 

/* Length */ 



/A**************************************************** 

/* Convert parameter pointers from character to hex addresses */ 

sscanf(argv??(l??),"%x",&Hlbptr); 
sscanf(argv??(2??),"%x\&Cmdbuf); 
sscanf(argv??(3??),"%x",&0rigblck); 

/•A*********************************************************** 

/* */ 

/* Execution */ 

/* */ 



Dsivarch msgbuf; 


char 


*cn; 


char 


*kw; 


char 


*kv; 


char 


*token; 


char 


cmdname??(9??) * 


char 


keyword?? (9??) = 


char 


keyvalue?? (9??)= 


int 


len; 
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/******************************************************************/ 



Scan the keyword and the value 



/* ...value 



/* Get length of key value 
/* Save keyvalue 
/* Pad with blanks? 
',8 - len); 



V 
*/ 



I* Syntax of command is: */ 

/* CMDNAME KEYWORD (KEYVALUE) */ 

/* Parse the command buffer for: */ 

token = strtok((char *) &(Cmdbuf->buffer)," "); /* ...COMMAND */ 
if (token != NULL) 

{ 

len = strl en (token); 
strcpy(cmdname, token) ; 
if (len < 8) 

strncat(cmdname," 
} 

token = strtok(NULL,"("); 
if (token != NULL) 

{ 

len = strl en (token); 
strcpy( keyword, token) ; 
if (len < 8) 

strncat( keyword," 
} 

token = strtok(NULL,")"); 
if (token != NULL) 

{ 

len = strlen(token); 
strcpy (keyvalue, token); 
if (len < 8) 

strncat( key value," 
} 

if (token != NULL) 

Cnmscop(cmdname, 

keyword, 

keyval ue) ; 
else 
Hlbptr->Hlbrc = CNM_BAD_ 



/* Get length of command name 
/* Save command name 
/* Pad with blanks? 
,8 - len); 



/* ...keyword 



/* Get length of keyword 
/* Save keyword 
/* Pad with blanks? 
\8 - len); 



V 

*/ 
*/ 



V 

*/ 



/* enough parms? 


*/ 


/* Scope check the input... 


*/ 


/* ...the command 


*/ 


/* ...the keyword 


V 


/* ...the value 


*/ 


/* not enough parms specified 


V 


INVOCATION;/* set bad re */ 
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/St*****************************************************************/ 

/* Inform user of the return code results... */ 

if (Hlbptr->Hlbrc == CNM_BAD INVOCATION) 

{ 
Cnmvlc(&msgbuf,0,"Not enough parms specified"); 
Cnmsmsg(&msgbuf,MSG,OPER,NULLCHAR); 

} 

else 
if (Hlbptr->Hlbrc == CNM_G00D) 

{ 
Cnmvlc(&msgbuf,0, "Operator has passed scope checking"); 
Cnmsmsg(&msgbuf,MSG,OPER,NULLCHAR); 

} 

else 
if (Hlbptr->Hlbrc == CNM_KEYWORD_NA) 

{ 
Cnmvlc(&msgbuf,0,"Not authorized to use KEYWORD %s", 

keyword) ; 
Cnmsmsg(&msgbuf,MSG,OPER,NULLCHAR); 

} 
else 

if (Hlbptr->Hlbrc == CNMJ/ALUE NA) 

{ 
Cnmvlc(&msgbuf,0,"Not authorized to use value %s", 

keyvalue); 
Cnmsmsg(&msgbuf,MSG,OPER,NULLCHAR); 

} 
else 

{ 
Cnmvlc(&msgbuf,0,"RC not recognized... %d", HI bptr->Hlbrc); 
Cnmsmsg (&msgbuf ,MSG,0PER , NULLCHAR) ; 

} 
Hlbptr->Hlbrc == CNM_G00D; /* clear return code */ 

} 
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Sample Command Processor for Sequential Logging 

This sample is an example of a command processor to log text to a sequential log. 

/•♦♦••it************************************************************ 

/* 7 

/* (C) COPYRIGHT IBM CORP. 1989 */ 

/* ' • V 

/* IEBCOPY SELECT MEMBER=((CNMS4249, CSEQLOG, R)) */ 

/* V 

/* Descriptive Name: High Level Language C sequential */ 

/* Logging Example */ 

/* */ 

/* Function: */ 

/* */ 

/* Write the text passed to this command procedure via the */ 

/* command line to the log. */ 

/* V 

/* The syntax of this command is: */ 

/* V 

/* CSEQLOG logtext */ 

/* */ 

/* Dependencies: None */ 

/* V 

/* Restrictions: The length of the text to be logged combined */ 

/* with the command name (CSEQLOG) can be no more */ 

/* than 255 characters. */ 

/* 7 

/* Language: C */ 

/* 7 

/* Installation: V 

/* 7 

/* (1) ASSEMBLE AND LINKEDIT THIS MODULE AM0DE=31,RM0DE=ANY */ 

/* TYPE=RENT */ 

/* (2) ALLOC PRIMARY AND SECONDARY SEQUENTIAL DATA SET */ 

/* (3) USE DD NMAES IN NETVIEW PROC OR THE ALLOCATE COMMAND */ 

/* TO ALLOCATE THE DATA SETS TO NETVIEW. */ 

/* ALLOCATE THE DATA SETS AS */ 

/* SQLOGP & SQLOGS */ 

/* (4) ADD THE FOLLOWING STATEMENT TO DSIDMN */ 

/* TASK M0D=DSIZDSTJSKID=SQL0GTSK,MEM=SQL0GMEM S PRI=3,INIT=Y*/ 

/* (5) ADD THE FOLLOWING MEMBER (SQLOGMEM) TO DSIPARM */ 

/* DSTINIT FUNCT=0THER,DSRB0=1 */ 

/* DSTINIT PBSDN=SQLOGP */ 

/* DSTINIT SBSDN=SQLOGS */ 

/* LOGINIT AUTOFLIP=YES,RESUME=NO */ 

/* (6) ADD THE FOLLOWING CMDMDL TO DSICMD */ 

/* CSEQLOG CMDMDL MOD=CSEQLOG,TYPE=R,RES=N */ 

/* 7 
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/* Input: */ 

/* 1) 4-byte pointer to the HLB control block */ 
/* 2) varying length character string of command (or message */ 

/* for user exits) that invoked this procedure */ 
/* 3) 40-byte parameter list which describes the origin of */ 
/* the request that caused execution of this procedure. */ 

/* V 

/* Output: */ 

/* Writes input to a sequential log */ 

/* V 

/* Return Codes: returned in HLBRC */ 

/* = normal exit */ 

/* -5 = canceled */ 

/* V 

/* External Module References: None */ 

/* V 

/* Change Activity: */ 

/* date, author: description of changes */ 

/* */ 

#pragma runopts (N0EXEC0PS,N0STAE,N0SPIE,ISASIZE(4K) ,ISAINC(4K)) 

/**************************************^ 

/* Standard include files 

/A*************************************************** 

#include <stdlib.h> /* Standard library */ 

#include <stdio.h> /* Standard i/o library */ 

#indude <stdarg.h> /* Standard args */ 

linclude <string.h> /* Standard args */ 

#define DOMAIN "DOMAIN " 

#define DATETIME "DATETIME" 

#define OPID "OPID 

#define SQTASK "SQLOGTSK" /* sequential log task id */ 

/***************************************^ 

/* NetView high level language include files */ 

#include "dsic.h" /* Include HLL macros */ 
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/* External data definitions */ 

/*****************************************************•**************; 

Dsihlb *Mbptr; /* Pointer to the HLB */ 

Dsivarch *Cmdbuf; /* Pointer to command buffer */ 

Dsiorig *0rigblck; /* Pointer to Orig block */ 

main(int argc, char *argv??(??)) 
{ 

/* Internal data definitions */ 

/it*****************************************************************/ 

Dsivarch domain, /* store domain name */ 

logtime, /* store time */ 

opid, /* store operator name */ 

logbfr, /* store the buffer to be logged */ 

message; /* store error message */ 

char logtext??(256??), /* store text passed on cmd line */ 
*token, /* used to parse command buffer */ 

*textptr; 

int size; 

/* Convert parameter pointers from character to hex addresses */ 

/•it****************************************************************/ 

sscanf (argv??(l??),"%x" J &Hlbptr); 
sscanf (argv?? (2??) , "%x" ,&Cmdbuf ) ; 
sscanf (argv?? (3??) , "%x" ,&0rigbl ck) ; 

/******************************************************************/ 
/* Initialization */ 

/* */ 

/* Customization starts here ... */ 

/* V 

/it*****************************************************************/ 
/••••♦•A***********************************************************/ 

/* V 

/* Execution */ 

/* V 

/••it***************************************************************/ 
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/************•***************************************************** / 

/* Parse command buffer for text to log */ 

/************************************************************ 

textptr = strchr((char *) &(Cmdbuf->buf fer) , ' '); 
size ■ 0; 

if (textptr != NULL) /* no text provided? */ 

{ 

textptr++; 

size = Cmdbuf->size - (textptr - ((char *) &(Cmdbuf->buffer))); 

} 

if ((size > 0) && (Cmdbuf->size < 255)) 
{ /*if text provided and not too big*/ 

Cnmi nfc (DOMAIN, &domain, 8); /* get the domain name */ 
Cnmi nfc(DATETIME,&l ogtime, 8);/* get the time */ 

Cnminfc(0PID,&opid,8); /* get the opid */ 

memmove (&1 ogtext?? (0??) , &(domai n. buf f er) ,domai n. si ze) ; 

logtext??(domain.size??) = ' '; 

memmove(&l ogtext?? (domai n . si ze+1??) ,&(1 ogtime . buffer) , 1 ogtime. si ze) ; 

logtext??(domain.size+logtime.size+l??) = ' ' ; 

memmove(&l ogtext?? (domai n . si ze+1 ogtime. si ze+2??) , 

&(opid.buffer) , opid. size) ; 
logtext??(domain.size+logtime.size+opid.size+2??) - ' '; 
meranove(&l ogtext?? (domain. size+1 ogtime. si ze+opid. si ze+3??), 
textptr, size); 

/* build the 1 ogtext in a varying */ 

Cnmnvlc(&logbfr, /* length character string... */ 

G, /* ...do not convert to hex */ 

domain. size+logtime.size+opid.size+size+3, /* ...size */ 

1 ogtext); /* ...text to be logged */ 

log the buffer... */ 

...text to be logged */ 

...type is message */ 

...dest type is sequential log */ 

...task defined by SQTASK */ 

/* Inform user of the return code results if Cnmsmsg fails */ 





/* 


Cnmsmsg (&logbfr, 


/* 


MSG, 


/* 


SEQLOG, 


/* 


SQTASK) ; 


/* 
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if (Hlbptr->Hlbrc -•= CNM_GOOD)/*if the return code was not zero 
{ 

/* build message in varying length 
Cnmvlc(&message, /* chararacter string... 

0, /* ...do not convert to hex 

"SL0G000 Error: Return code from Cnmsmsg = %d", 
Hlbptr->Hlbrc); /* ...message text 



7 

*/ 

V 
V 



Cnmsmsg (&message, 

MSG, 

OPER, 

NULLCHAR) ; 
} 




/* display message... 

/* ...type is message 

/* ...send to oper that issued s 

/* ...not used 


*/ 

7 

log*/ 
7 


} 
else 
if (size <= 0) 
{ 

Cnmvlc(&message, 
0, 
"No text has been 


/* No text to log */ 
/* put error message in varying */ 
/* length character string... */ 
/* ...do not convert to hex */ 
provided for logging"); /* message text*/ 


Cnmsmsg (&mes sage, 
MSG, 
OPER, 
NULLCHAR); 

} 
else if (Cmdbuf->size > 

{ 

Cnmvlc (tones sage, 
0, 
"Text to be lo< 




/* display message... 

/* ...message to display 

/* ...type is message 

/* ...send to invoking operator 

/* ...not used 


7 
7 

7 
7 
7 


255) 
gged ■ 


/* text too long */ 
/* put error message in varying */ 
/* length character string... */ 
/* ...do not convert to hex */ 
is too long"); /* message text*/ 


Cnmsmsg (Stmessage, 
MSG, 
OPER, 
NULLCHAR) ; 




/* display message... 

/* ...message to display 

/* ...type is message 

/* ...send to invoking operator 

/* ...not used 


7 
7 
7 
7 
7 
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Glossary 



This glossary defines important NCP, NetView, 
NetView/PC, SSP, and VTAM abbreviations and terms. 
It includes information from the IBM Dictionary of Com- 
puting, SC20-1699. Definitions from the American 
National Dictionary for Information Processing are 
identified by an asterisk (*). Definitions from draft pro- 
posals and working papers under development by the 
International Standards Organization, Technical Com- 
mittee 97, Subcommittee 1 are identified by the symbol 
(TC97). Definitions from the CCITT Sixth Plenary 
Assembly Orange Book, Terms and Definitions and 
working documents published by the Consultative Com- 
mittee on International Telegraph and Telephone of the 
International Telecommunication Union, Geneva, 1980 
are preceded by the symbol (CCITT/ITU). Definitions 
from published sections of the ISO Vocabulary of Data 
Processing, developed by the International Standards 
Organization, Technical Committee 97, Subcommittee 1 
and from published sections of the ISO Vocabulary of 
Office Machines, developed by subcommittees of ISO 
Technical Committee 95, are preceded by the symbol 
(ISO). 

For abbreviations, the definition usually consists only of 
the words represented by the letters; for complete defi- 
nitions, see the entries for the words. 

Reference Words Used in the Entries 

The following reference words are used in this 
glossary: 

Deprecated term for. Indicates that the term should 
not be used. It refers to a preferred term, which is 
defined. 

Synonymous with. Appears in the commentary of a 
preferred term and identifies less desirable or less 
specific terms that have the same meaning. 

Synonym for. Appears in the commentary of a less 
desirable or less specific term and identifies the 
preferred term that has the same meaning. 

Contrast with. Refers to a term that has an opposed 
or substantively different meaning. 

See. Refers to multiple-word terms that have the 
same last word. 

See a/so. Refers to related terms that have similar 
(but not synonymous) meanings. 



abend. Abnormal end of task. 



ACB. (1) In VTAM, access method control block. 
(2) In NCP, adapter control block. 

ACB name. (1) The name of an ACB macroinstruction. 
(2) A name specified in the ACBNAME parameter of a 
VTAM APPL statement. Contrast with network name. 

accept. For a VTAM application program, to establish 
a session with a logical unit (LU) in response to a CINIT 
request from a system services control point (SSCP). 
The session-initiation request may begin when a ter- 
minal user logs on, a VTAM application program issues 
a macroinstruction, or a VTAM operator issues a 
command. See also acquire (1). 

access method control block (ACB). A control block 
that links an application program to VSAM or VTAM. 

accounting exit routine. In VTAM, an optional installa- 
tion exit routine that collects statistics about session 
initiation and termination. 

ACF/NCP. Advanced Communications Function for the 
Network Control Program. Synonym for NCP. 

ACF/SSP. Advanced Communications Function for the 
System Support Programs. Synonym for SSP. 

ACF/VTAM. Advanced Communications Function for 
the Virtual Telecommunications Access Method. 
Synonym for VTAM. 

acquire. (1) For a VTAM application program, to ini- 
tiate and establish a session with another logical unit 
(LU). The acquire process begins when the application 
program issues a macroinstruction. See also accept. 
(2) To take over resources that were formerly con- 
trolled by an access method in another domain, or to 
resume control of resources that were controlled by 
this domain but released. Contrast with release. See 
also resource takeover. 

activate. To make a resource of a node ready to 
perform the functions for which it was designed. Con- 
trast with deactivate. 

active. (1) The state a resource is in when it has been 
activated and is operational. Contrast with inactive, 
pending, and inoperative.. (2) Pertaining to a major or 
minor node that has been activated by VTAM. Most 
resources are activated as part of VTAM start proc- 
essing or as the result of a VARY ACT command. 



abnormal end of task (abend). Termination of a task 
before its completion because of an error condition that 
cannot be resolved by recovery facilities while the task 
is executing. 



adapter control block (ACB). In NCP, a control block 
that contains line control information and the states of 
I/O operations for BSC lines, SS lines, or SDLC links. 
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adaptive session pacing. 

session-level pacing. 



Synonym for adaptive 



adaptive session-level pacing. A form of session-level 
pacing in which session components exchange pacing 
windows that may vary in size during the course of a 
session. This allows transmission to adapt dynamically 
to variations in availability and demand of buffers on a 
session by session basis. Session pacing occurs 
within independent stages along the session path 
according to local congestion at the intermediate 
nodes. Synonymous with adaptive session pacing. 
See pacing, session-level pacing, and virtual route 
pacing. 

alert. (1) In SNA, a record sent to a system problem 
management focal point to communicate the existence 
of an alert condition. (2) In the NetView program, a 
high priority event that warrants immediate attention. 
This data base record is generated for certain event 
types that are defined by user-constructed filters. 

alias name. A name defined in a host used to repre- 
sent a logical unit name, logon mode table name, or 
class-of-service name in another network. This name 
is defined to a name translation program when the 
alias name does not match the real name. The alias 
name translation program is used to associate the real 
and alias names. 

allocate. A logical unit (LU) 6.2 application program 
interface (API) verb used to assign a session to a con- 
versation for the conversation's use. Contrast with 
deallocate. 



and authorized-receiver messages not assigned to a 
specific operator. 

automatic logon. (1) A process by which VTAM auto- 
matically creates a session-initiation request to estab- 
lish a session between two logical units (LUs). The 
session will be between a designated primary logical 
unit (PLU) and a secondary logical unit (SLU) that is 
neither queued for nor in session with another PLU. 
See also controlling application program and control- 
ling logical unit. (2) In VM, a process by which a 
virtual machine is initiated by other than the user of 
that virtual machine. For example, the primary VM 
operator's virtual machine is activated automatically 
during VM initialization. 

available. In VTAM, pertaining to a logical unit that is 
active, connected, enabled, and not at its session limit. 

begin bracket. In SNA, the value (binary 1) of the 
begin-bracket indicator in the request header (RH) of 
the first request in the first chain of a bracket; the value 
denotes the start of a bracket. Contrast with end 
bracket. See also bracket. 

BIU segment. In SNA, the portion of a basic informa- 
tion unit (BIU) that is contained within a path informa- 
tion unit (PIU). It consists of either a request/response 
header (RH) followed by all or a portion of a 
request/response unit (RU), or only a portion of an RU. 

blocking of PIUs. In SNA, an optional function of path 
control that combines multiple path information units 
(PIUs) into a single basic transmission unit (BTU). 



API. Application program interface. 

application program. (1) A program written for or by a 
user that applies to the user's work. (2) A program 
used to connect and communicate with stations in a 
network, enabling users to perform application-oriented 
activities. 

application program interface (API). (1) The formally 
defined programming language interface between an 
IBM system control program or licensed program and 
its user. (2) The interface through which an application 
program interacts with an access method. In VTAM, it 
is the language structure used in control blocks so that 
application programs can reference them and be identi- 
fied to VTAM. 

attaching device. Any device that is physically con- 
nected to a network and can communicate over the 
network. 



boundary function. (1) A capability of a subarea node 
to provide protocol support for attached peripheral 
nodes, such as: (a) interconnecting subarea path 
control and peripheral path control elements, (b) per- 
forming session sequence numbering for low-function 
peripheral nodes, and (c) providing session-level 
pacing support. (2) The component that provides these 
capabilities. See also boundary node, network 
addressable unii (NAU), peripheral path control, 
subarea node, and subarea path control. 

boundary node. (1) A subarea node with boundary 
function. See subarea node (including illustration). 
See also boundary function. (2) The programming 
component that performs FID2 (format identification 
type 2) conversion, channel data link control, pacing, 
and channel or device error recovery procedures for a 
locally attached station. These functions are similar to 
those performed by a network control program for an 
NCP-attached station. 



authorization exit routine. In VTAM, an optional instal- 
lation exit routine that approves or disapproves 
requests for session initiation. 

authorized receiver. In the NetView program, an 
authorized operator who receives all the unsolicited 



bracket. In SNA, one or more chains of request units 
(RUs) and their responses that are exchanged between 
the two LU-LU half-sessions and that represent a trans- 
action between them. A bracket must be completed 
before another bracket can be started. Examples of 
brackets are data base inquiries/replies, update trans- 
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actions, and remote job entry output sequences to work 
stations. See also begin bracket and end bracket. 

browse. A way of looking at a file that does not allow 
you to change it. 

buffer. A portion of storage for temporarily holding 
input or output data. 

call. (1) * (ISO) The action of bringing a computer 
program, a routine, or a subroutine into effect, usually 
by specifying the entry conditions and jumping to an 
entry point. (2) To transfer control to a procedure, 
program, routine, or subroutine. (3) The actions nec- 
essary to make a connection between two stations. 
(4) To attempt to contact a user, regardless of whether 
the attempt is successful. 

CALLOUT. The logical channel type on which the data 
terminal equipment (DTE) can send a call, but cannot 
receive one. 

calling. * (ISO) The process of transmitting selection 
signals in order to establish a connection between data 
stations. 

CCP. Configuration control program facility. 

CDRM. Cross-domain resource manager. 

CDRSC. Cross-domain resource. 

chain. (1) A group of logically linked records. (2) See 
RU chain. 

channel. * A path along which signals can be sent, for 
example, data channel, output channel. See data 
channel and input/output channel. See also link. 

channel-attached. (1) Pertaining to the attachment of 
devices directly by input/output channels to a host 
processor. (2) Pertaining to devices attached to a con- 
trolling unit by cables, rather than by telecommuni- 
cation lines. Contrast with link-attached. Synonymous 
with local. 

character-coded. Synonym for unformatted. 

class of service (COS). In SNA, a designation of the 
path control network characteristics, such as path 
security, transmission priority, and bandwidth, that 
apply to a particular session. The end user designates 
class of service at session initiation by using a sym- 
bolic name that is mapped into a list of virtual routes, 
any one of which can be selected for the session to 
provide the requested level of service. 

cleanup. A network services request, sent by a system 
services control unit (SSCP) to a logical unit (LU), that 
causes a particular LU-LU session with that LU to be 
ended immediately and without the participation of 
either the other LU or its SSCP. 



CLIST. Command list. 

CNM. Communication network management. 

code point. In the NetView/PC program and in the 
NetView program, a 1- or 2-byte hexadecimal value that 
indexes a text string stored at an alert receiver and is 
used by the alert receiver to create displays of alert 
information. 

command. (1) A request from a terminal for the per- 
formance of an operation or the execution of a partic- 
ular program. (2) In SNA, any field set in the 
transmission header (TH), request header (RH), and 
sometimes portions of a request unit (RU), that initiates 
an action or that begins a protocol; for example: (a) 
Bind Session (session-control request unit), a 
command that activates an LU-LU session, (b) the 
change-direction indicator in the RH of the last RU of a 
chain, (c) the virtual route reset window indicator in a 
FID4 transmission header. See also VTAM operator 
command. 

command facility. The component of the NetView 
program that is a base for command processors that 
can monitor, control, automate, and improve the opera- 
tion of a network. 

command list. A list of commands and statements 
designed to perform a specific function for the user. 
Command lists can be written in REXX or in NetView 
command list language. 

command procedure. Either a command processor 
written in a high-level language (HLL) or a command 
list. See also command list and command processor. 

command processor. (1) A program that performs an 
operation specified by a command. (2) In the NetView 
program, a user-written module designed to perform a 
specific function. Command processors, which can be 
written in assembler or a high-level language (HLL), 
are invoked as commands. 

communication line. Deprecated term for telecommu- 
nication line and transmission line. 

communication management configuration host node. 

The type 5 host processor in a communication manage- 
ment configuration that does all network-control func- 
tions in the network except for the control of devices 
channel-attached to data hosts. Synonymous with com- 
munication management host. Contrast with data host 
node. 

communication management host. Synonym for com- 
munication management configuration host node. Con- 
trast with data host. 

communication network management (CNM). The 

process of designing, installing, operating, and man- 
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aging the distribution of information and controls 
among end users of communication systems. 

communication network management (CNM) applica- 
tion program. A VTAM application program that issues 
and receives formatted management services request 
units for physical units. For example, the NetView 
program. 

communication network management (CNM) Interface. 

The interface that the access method provides to an 
application program for handling data and commands 
associated with communication system management. 
CNM data and commands are handled across this inter- 
face. 

communication network management (CNM) 
processor. A program that manages one of the func- 
tions of a communications system. A CNM processor is 
executed under control of the NetView program. 

component. A command that (a) controls the termi- 
nal's screen (using the DSIPSS macro 
(TYPE = ASYPANEL) or the VIEW command), (b) allows 
the operator to enter NetView commands, and (c) can 
resume when such commands are complete. 

composite end node (CEN). A group of nodes made up 
of a single type 5 node and its subordinate type 4 nodes 
that together support type 2.1 protocols. To a type 2.1 
node, a CEN appears as one end node. For example, 
NCP and VTAM act as a composite end node. 

configuration. (1) (TC97) The arrangement of a com- 
puter system or network as defined by the nature, 
number, and the chief characteristics of its functional 
units. The term may refer to a hardware or a software 
configuration. (2) The devices and programs that 
make up a system, subsystem, or network. (3) In CCP, 
the arrangement of controllers, lines, and terminals 
attached to an IBM 3710 Network Controller. Also, the 
collective set of item definitions that describe such a 
configuration. 

configuration control program (CCP) facility. An SSP 

interactive application program facility by which config- 
uration definitions for the IBM 3710 Network Controller 
can be created, modified, and maintained. 

configuration restart. In SNA, one of the types of 
network services in the control point (CP) and in the 
physical unit (PU); configuration services activate, 
deactivate, and maintain the status of physical units, 
links, and link stations. Configuration services also 
shut down and restart network elements and modify 
path control routing tables and address-translation 
tables. See also maintenance services, management 
services, network services, and session services. 

connection. Synonym for physical connection. 



control block. (1) (ISO) A storage area used by a 
computer program to hold control information. (2) In 
the IBM Token-Ring Network, a specifically formatted 
block of information provided from the application 
program to the Adapter Support Interface to request an 
operation. 

control program (CP). The VM operating system that 
manages the real processor's resources and is respon- 
sible for simulating System/370s for individual users. 

controlling application program. In VTAM, an applica- 
tion program with which a secondary logical unit (other 
than an application program) is automatically put in 
session whenever the secondary logical unit is avail- 
able. See also automatic logon and controlling logical 
unit. 

controlling logical unit. In VTAM, a logical unit with 
which a secondary logical unit (other than an applica- 
tion program) is automatically put in session whenever 
the secondary logical unit is available. A controlling 
logical unit can be either an application program or a 
device-type logical unit. See also automatic logon and 
controlling application program. 

converted command. An intermediate form of a 
character-coded command produced by VTAM through 
use of an unformatted system services definition table. 
The format of a converted command is fixed; the unfor- 
matted system services definition table must be con- 
structed in such a manner that the character-coded 
command (as entered by a logical unit) is converted 
into the predefined, converted command format. See 
also unformatted. 

COS. Class of service. 

cross-domain. In SNA, pertaining to control of 
resources involving more than one domain. 

cross-domain resource (CDRSC). A resource owned 
by a cross-domain resource manager (CDRM) in 
another domain but known by the CDRM in this domain 
by network name and associated CDRM. 

cross-domain resource manager (CDRM). In VTAM, 
the function in the system services control point (SSCP) 
that controls initiation and termination of cross-domain 
sessions. 

data channel. Synonym for input/output channel. See 
channel. 

data flow control (DFC) layer. In SNA, the layer within 
a half-session that (1) controls whether the half-session 
can send, receive, or concurrently send and receive 
request units (RUs); (2) groups related RUs into RU 
chains; (3) delimits transactions via the bracket pro- 
tocol; (4) controls the interlocking of requests and 
responses in accordance with control modes specified 



320 NetView Customization: Using PLI and C 



at session activation; (5) generates sequence numbers; 
and (6) correlates requests and responses. 

data host. Synonym for data host node. Contrast with 
communication management configuration host. 



definition statement. (1) In VTAM, the statement that 
describes an element of the network. (2) In NCP, a 
type of instruction that defines a resource to the NCP. 
See Figure 13, Figure 14, and Figure 15. See also 
macroinstruction. 



data host node. In a communication management con- 
figuration, a type 5 host node that is dedicated to proc- 
essing applications and does not control network 
resources, except for its channel-attached or communi- 
cation adapter-attached devices. Synonymous with 
data host. Contrast with communication management 
configuration host node. 

data link. In SNA, synonym for link. 
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data link control (DLC) layer. In SNA, the layer that 
consists of the link stations that schedule data transfer 
over a transmission medium connecting two nodes and 
perform error control for the link connection. Examples 
of data link control are SDLC for serial-by-bit link con- 
nection and data link control for the System/370 
channel. 

data services command processor (DSCP). A compo- 
nent that structures a request for recording and 
retrieving data in the application program's data base 
and for soliciting data from a device in the network. 

data services manager (DSM). A function in the 
NetView program that provides VSAM services for data 
storage and retrieval. 

data services task (DST). The NetView subtask that 
gathers, records, and manages data in a VSAM file 
and/or a network device that contains network manage- 
ment information. 

data set. The major unit of data storage and retrieval, 
consisting of a collection of data in one of several pre- 
scribed arrangements and described by control infor- 
mation to which the system has access. 

ddname. Data definition name. 

deactivate. To take a resource of a node out of 
service, rendering it inoperable, or to place it in a state 
in which it cannot perform the functions for which it was 
designed. Contrast with activate. 

deallocate. A logical unit (LU) 6.2 application program 
interface (API) verb that terminates a conversation, 
thereby freeing the session for a future conversation. 
Contrast with allocate. 

definite response (DR). In SNA, a value in the 
form-of-response-requested field of the request header. 
The value directs the receiver of the request to return a 
response unconditionally, whether positive or negative, 
to that request. Contrast with exception response and 
no response. 
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device. An input/output unit such as a terminal, 
display, or printer. See attaching device. 

directory. In VM, a control program (CP) disk that 
defines each virtual machine's normal configuration. 

display. (1) To present information for viewing, 
usually on a terminal screen or a hard-copy device. 
(2) A device or medium on which information is pre- 
sented, such as a terminal screen. (3) Deprecated 
term for panel. 
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domain. (1) An access method, its application pro- 
grams, communication controllers, connecting lines, 
modems, and attached terminals. (2) In SNA, a system 
services control point (SSCP) and the physical units 
(PUs), logical units (LUs), links, link stations, and all the 
associated resources that the SSCP has the ability to 
control by means of activation requests and deacti- 
vation requests. See system services control point 
domain and type 2.1 node control point domain.. See 
also single-domain network and multiple-domain 
network. 

domain operator. In a multiple-domain network, the 
person or program that controls the operation of the 
resources controlled by one system services control 
point. Contrast with network operator (2). 

double-byte character set (DBCS). A character set, 
such as Japanese, in which each character is repres- 
ented by a two-byte code. 

downstream. In the direction of data flow from the host 
to the end user. Contrast with upstream. 



enciphered data (ED). Data whose meaning is con- 
cealed from unauthorized users. 

end bracket. In SNA, the value (binary 1) of the end 
bracket indicator in the request header (RH) of the first 
request of the last chain of a bracket; the value denotes 
the end of the bracket. Contrast with begin bracket. 
See also bracket. 

end node. A type 2.1 node that does not provide any 
intermediate routing or session services to any other 
node. For example, APPC/PC is an end node. See 
composite end node, node, and fype 2.1 node. 

entry point. An SNA node that provides distributed 
network management support. It may be a type 2, type 
2.1, type 4, or type 5 node. It sends SNA-formatted 
network management data about itself and the 
resources it controls to a focal point for centralized 
processing, and it receives and executes focal point ini- 
tiated commands to manage and control its resources. 

EP. Emulation Program. 



drop. In the IBM Token-Ring Network, a cable that 
leads from a faceplate to the to the distribution panel in 
a wiring closet. When the IBM Cabling System is used 
with the IBM Token-Ring Network, a drop may form part 
of a lobe. 

DSCP. Data services command processor. 

DSM. Data services manager. 

DST. Data services task. 

dump. (1) Computer printout of storage. (2) To write 
the contents of all or part of storage to an external 
medium as a safeguard against errors or in connection 
with debugging. (3) (ISO) Data that have been 
dumped. 

EBCDIC. * Extended binary-coded decimal inter- 
change code. A coded character set consisting of 8-bit 
coded characters. 



ER. (1) Explicit route. (2) Exception response. 

ESTAE. Extended specify task abnormal exit. 

event. (1) In the NetView program, a record indicating 
irregularities of operation in physical elements of a 
network. (2) An occurrence of significance to a task; 
typically, the completion of an asynchronous operation, 
such as an input/output operation. 

exception response (ER). In SNA, a value in the 
form-of-response-requested field of a request header 
(RH). An exception response is sent only if a request is 
unacceptable as received or cannot be processed. 
Contrast with definite response and no response. See 
also negative response. 

EXEC. In a VM operating system, a user-written 
command file that contains CMS commands, other 
user-written commands, and execution control state- 
ments, such as branches. 



echo. The return of characters to the originating SS 
device to verify that a message was sent correctly. 

ED. Enciphered data. 

element. (1) A field in the network address. (2) The 
particular resource within a subarea identified by the 
element address. See also subarea. 

Emulation Program (EP). An IBM control program that 
allows a channel-attached 3705 or 3725 communication 
controller to emulate the functions of an IBM 2701 Data 
Adapter Unit, an IBM 2702 Transmission Control, or an 
IBM 2703 Transmission Control. See also network 
control program. 



exit routine. Any of several types of special-purpose 
user-written routines. See accounting exit routine, 
authorization exit routine, logon-interpret routine, 
virtual route selection exit routine, EXLST exit routine, 
and RPL exit routine. 

EXLST exit routine. In VTAM, a routine whose address 
has been placed in an exit list (EXLST) control block. 
The addresses are placed there with the EXLST macro- 
instruction, and the routines are named according to 
their corresponding operand; hence DFASY exit 
routine, TPEND exit routine, RELREQ exit routine, and 
so forth. All exit list routines are coded by the VTAM 
application programmer. Contrast with RPL exit 
routine. 
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explicit route (ER). In SNA, the path control network 
elements, including a specific set of one or more trans- 
mission groups, that connect two subarea nodes. An 
explicit route is identified by an origin subarea 
address, a destination subarea address, an explicit 
route number, and a reverse explicit route number. 
Contrast with virtual route (VR). See also path and 
route extension. 



group. In the NetView/PC program, to identify a set of 
application programs that are to run concurrently. 

half-session. In SNA, a component that provides func- 
tion management data (FMD) services, data flow 
control, and transmission control for one of the ses- 
sions of a network addressable unit (NAU). See also 
primary half-session and secondary half-session. 



extended specify task abnormal exit (ESTAE). An MVS 

macroinstruction that provides recovery capability and 
gives control to the user-specified exit routine for proc- 
essing, diagnosing an abend, or specifying a retry 
address. 

field-formatted. Pertaining to a request or response 
that is encoded into fields, each having a specified 
format such as binary codes, bit-significant flags, and 
symbolic names. Contrast with character-coded. 

flow control. In SNA, the process of managing the rate 
at which data traffic passes between components of the 
network. The purpose of flow control is to optimize the 
rate of flow of message units, with minimum congestion 
in the network; that is, to neither overflow the buffers at 
the receiver or at intermediate routing nodes, nor leave 
the receiver waiting for more message units. See also 
adaptive session-level pacing, pacing, session-level 
pacing, and virtual route pacing. 

focal point. An entry point that provides centralized 
management and control for other entry points for one 
or more network management categories. 

formatted system services. A portion of VTAM that 
provides certain system services as a result of 
receiving a field-formatted command, such as an Ini- 
tiate or Terminate command. Contrast with unfor- 
matted system services (USS). See also 
field-formatted. 



hard copy. A printed copy of machine output in a visu- 
ally readable form; for example, printed reports, 
listings, documents, summaries, or network logs. 

hardware monitor. The component of the NetView 
program that helps identify network problems, such as 
hardware, software, and microcode, from a central 
control point using interactive display techniques. 

help panel. An online display that tells you how to use 
a command or another aspect of a product. See task 
panel. 

high-level language (HLL). A programming language 
that does not reflect the structure of any particular com- 
puter or operating system. For NetView Release 3, the 
high-level languages are PL/I and C. 

hierarchy. In the NetView program, the resource 
types, display types, and data types that make up the 
organization, or levels, in a network. 

host node. A node providing an application program 
interface (API) and a common application interface. 
See boundary node, node, peripheral node, subarea 
host node, and subarea node. See also boundary func- 
tion and node type. 

immediate command. In the NetView program, a 
command (such as GO, CANCEL, or RESET) that can be 
executed while a regular command is being processed. 



frame. (1) The unit of transmission in some local area 
networks, including the IBM Token-Ring Network. It 
includes delimiters, control characters, information, 
and checking characters. (2) In SDLC, the vehicle for 
every command, every response, and all information 
that is transmitted using SDLC procedures. 

full-screen mode. A form of panel presentation in the 
NetView program where the contents of an entire ter- 
minal screen can be displayed at once. Full-screen 
mode can be used for fill-in-the-blanks prompting. Con- 
trast with line mode. 

generation. The process of assembling and link 
editing definition statements so that resources can be 
identified to all the necessary programs in a network. 

generic alert. Encoded alert information that uses 
code points (defined by IBM and possibly customized 
by users or application programs) stored at an alert 
receiver, such as the NetView program. 



inactive. Describes the state of a resource that has not 
been activated or for which the VARY INACT command 
has been issued. Contrast with active. See also inop- 
erative. 



information (I) format. 

transfer. 



A format used for information 



initiate. A network services request sent from a logical 
unit (LU) to a system services control point (SSCP) 
requesting that an LU-LU session be established. 

inoperative. The condition of a resource that has been 
active, but is not. The resource may have failed, 
received an INOP request, or is suspended while a 
reactivate command is being processed. See also 
inactive. 

input/output channel. (1) (ISO) In a data processing 
system, a functional unit that handles the transfer of 
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data between internal and peripheral equipment. (2) In 
a computing system, a functional unit, controlled by a 
processor, that handles the transfer of data between 
processor storage and local peripheral devices. Syn- 
onymous with data channel. See channel. See also 
link. 

interface. * A shared boundary. An interface might be 
a hardware component to link two devices or it might 
be a portion of storage or registers accessed by two or 
more computer programs. 

item. In CCP, any of the components, such as commu- 
nication controllers, lines, cluster controllers, and ter- 
minals, that comprise an IBM 3710 Network Controller 
configuration. 

JCL. Job control language. 

job control language (JCL). * A problem-oriented lan- 
guage designed to express statements in a job that are 
used to identify the job or describe its requirements to 
an operating system. 

Kanji. An ideographic character set used in Japanese. 
See also double-byte character set. 

keyword. (1) (TC97) A lexical unit that, in certain con- 
texts, characterizes some language construction. (2) * 
One of the predefined words of an artificial language. 
(3) One of the significant and informative words in a 
title or document that describes the content of that doc- 
ument. (4) A name or symbol that identifies a param- 
eter. (5) A part of a command operand that consists of 
a specific character string (such as DSNAME = ). See 
also definition statement and keyword operand. Con- 
trast with positional operand. 

keyword operand. An operand that consists of a 
keyword followed by one or more values (such as 
DSNAME = HELLO). See also definition statement. 
Contrast with positional operand. 

keyword parameter. A parameter that consists of a 
keyword followed by one or more values. 

LCS. Link connection subsystem. 

line. See communication line. 

line mode. A form of screen presentation in which the 
information is presented a line at a time in the message 
area of the terminal screen. Contrast with full-screen 
mode. 

link. In SNA, the combination of the link connection 
and the link stations joining network nodes; for 
example: (1) a System/370 channel and its associated 
protocols, (2) a serial-by-bit connection under the 
control of Synchronous Data Link Control (SDLC). A 
link connection is the physical medium of transmission. 



A link, however, is both logical and physical. Synony- 
mous with data link. See Figure 16 on page 325. 

link-attached. Pertaining to devices that are physically 
connected by a telecommunication line. Contrast with 
channel-attached. Synonymous with remote. 



link connection subsystem (LCS). The sequence of 
connection components (LCCs) that belong to a link 
connection and are managed by one LCSM. 



ink 



load module. (ISO) A program unit that is suitable for 
loading into main storage for execution; it is usually the 
output of a linkage editor. 

local. Pertaining to a device that is attached to a con- 
trolling unit by cables, rather than by a telecommuni- 
cation line. Synonymous with channel-attached. 

local address. In SNA, an address used in a peripheral 
node in place of an SNA network address and trans- 
formed to or from an SNA network address by the 
boundary function in a subarea node. 

logical unit (LU). In SNA, a port through which an end 
user accesses the SNA network and the functions pro- 
vided by system services control points (SSCPs). An 
LU can support at least two sessions— one with an 
SSCP and one with another LU— and may be capable of 
supporting many sessions with other LUs. See also 
network addressable unit (NAU), peripheral LU, phys- 
ical unit (PU), system services control point (SSCP), 
primary logical unit (PLU), and secondary logical unit 
(SLU). 

logical unit (LU) services. In SNA, capabilities in a 
logical unit to: (1) receive requests from an end user 
and, in turn, issue requests to the system services 
control point (SSCP) in order to perform the requested 
functions, typically for session initiation; (2) receive 
requests from the SSCP, for example to activate LU-LU 
sessions via Bind Session requests; and (3) provide 
session presentation and other services for LU-LU ses- 
sions. See also physical unit (PU) services. 

logical unit (LU) 6.2. A type of logical unit that sup- 
ports general communication between programs in a 
distributed processing environment. LU 6.2 is charac- 
terized by (1) a peer relationship between session part- 
ners, (2) efficient utilization of a session for multiple 
transactions, (3) comprehensive end-to-end error proc- 
essing, and (4) a generic application program interface 
(API) consisting of structured verbs that are mapped 
into a product implementation. 

logmode table. Synonym for logon mode table. 

logoff. In VTAM, an unformatted session termination 
request. 

logon. In VTAM, an unformatted session initiation 
request for a session between two logical units. See 
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Figure 16. Links and Path Controls 

automatic logon and simulated logon. See also 
session-initiation request. 

logon mode table. In VTAM, a set of entries for one or 
more logon modes. Each logon mode is identified by a 
logon mode name. Synonymous with logmode table. 



logon-interpret routine. In VTAM, an installation exit 
routine, associated with an interpret table entry, that 
translates logon information. It may also verify the 
logon. 

LU. Logical unit. 
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LU type. In SNA, the classification of an LU-LU session 
in terms of the specific subset of SNA protocols and 
options supported by the logical units (LUs) for that 
session, namely: 

The mandatory and optional values allowed in the 
session activation request. 

The usage of data stream controls, function man- 
agement headers (FMHs), request unit (RU) param- 
eters, and sense codes. 

Presentation services protocols such as those 
associated with FMH usage. 

LU types 0, 1, 2, 3, 4, 6.1, 6.2, and 7 are defined. 

LU-LU session, in SNA, a session between two logical 
units (LUs) in an SNA network. It provides communi- 
cation between two end users, or between an end user 
and an LU services component. 

LU-LU session type. A deprecated term for LU type. 

LU 6.2. Logical unit 6.2. 

macroinstruction. (1) An instruction that when exe- 
cuted causes the execution of a predefined sequence of 
instructions in the same source language. (2) In 
assembler programming, an assembler language state- 
ment that causes the assembler to process a prede- 
fined set of statements called a macro definition. The 
statements normally produced from the macro defi- 
nition replace the macroinstruction in the program. 
See also definition statement. 

maintenance services. In SNA, one of the types of 
network services in system services control points 
(SSCPs) and physical units (PUs). Maintenance ser- 
vices provide facilities for testing links and nodes and 
for collecting and recording error information. See 
also configuration services, management services, 
network services, and session services. 

major node. In VTAM, a set of resources that can be 
activated and deactivated as a group. See node and 
minor node. 

management services. In SNA, one of the types of 
network services in control points (CPs) and physical 
units (PUs). Management services are the services 
provided to assist in the management of SNA networks, 
such as problem management, performance and 
accounting management, configuration management 
and change management. See also configuration ser- 
vices, maintenance services, network services, and 
session services. 

Medium Access Control (MAC). The sublayer of OLC 
that supports medium-dependent functions and uses 
the services of the physical layer to provide services to 
Logical Link Control (LLC). The MAC sublayer includes 
the medium access port. 



medium access control (MAC) procedure. (TC97) In a 
local area network, the part of the protocol that governs 
access to the transmission medium independently of 
the physical characteristics of the medium, but takes 
into account the topological aspects of the network, in 
order to enable the exchange of data between data 
stations. 

message. (1) (TC97) A group of characters and 
control bit sequences transferred as an entity. (2) In 
VTAM, the amount of function management data (FMD) 
transferred to VTAM by the application program with 
one SEND request. 

migration. Installing a new version or release of a 
program when an earlier version or release is already 
in place. 

minor node. In VTAM, a uniquely-defined resource 
within a major node. See node and major node. 

module. * A program unit that is discrete and identifi- 
able with respect to compiling, combining with other 
units, and loading; for example, the input to or output 
from an assembler, compiler, linkage editor, or execu- 
tive routine. 

monitor. In the IBM Token-Ring Network, the function 
required to initiate the transmission of a token on the 
ring and to provide soft-error recovery in case of lost 
tokens, circulating frames, or other difficulties. The 
capability is present in all ring stations. 

multiple-domain network. In SNA, a network with more 
than one system services control point (SSCP). Con- 
trast with single-domain network. 

Multiple Virtual Storage (MVS). An IBM licensed 
program whose full name is the Operating 
System/Virtual Storage (OS/VS) with Multiple Virtual 
Storage/System Product for System/370. It is a soft- 
ware operating system controlling the execution of pro- 
grams. 

Multiple Virtual Storage for Extended Architecture 
(MVS/XA). An IBM licensed program whose full name 
is the Operating System/Virtual Storage (OS/VS) with 
Multiple Virtual Storage/System Product for Extended 
Architecture. Extended architecture allows 31-bit 
storage addressing. MVS/XA is a software operating 
system controlling the execution of programs. 

MVS. Multiple Virtual Storage operating system. 

MVS/XA. Multiple Virtual Storage for Extended Archi- 
tecture operating system. 

NAU. Network addressable unit. 

NC. Network control. 

NCCF. Network Communications Control Facility. 
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NCP. (1) Network Control Program (IBM licensed 
program). Its full name is Advanced Communications 
Function for the Network Control Program. Synony- 
mous with ACF/NCP. (2) Network control program 
(general term). 

negative response (NR). In SNA, a response indicating 
that a request did not arrive successfully or was not 
processed successfully by the receiver. Contrast with 
positive response. See exception response. 

NetView. A system 370-based IBM licensed program 
used to monitor a network, manage it, and diagnose its 
problems. 

NetView command list language. An interpretive lan- 
guage unique to the NetView program that is used to 
write command lists. 

NetView-NetView task (NNT). The task under which a 
cross-domain NetView operator session runs. See 
operator station task. 

NetView/PC. A PC-based IBM licensed program 
through which application programs can be used to 
monitor, manage, and diagnose problems in IBM 
Token-Ring networks, non-SNA communication 
devices, and voice networks. 

network. (1) (TC97) An interconnected group of 
nodes. (2) In data processing, a user application 
network. See path control network, public network, 
SNA network, subarea network, type 2.1 network, and 
user-application network. 

network address. In SNA, an address, consisting of 
subarea and element fields, that identifies a link, a link 
station, or a network addressable unit. Subarea nodes 
use network addresses; peripheral nodes use local 
addresses. The boundary function in the subarea node 
to which a peripheral node is attached transforms local 
addresses to network addresses and vice versa. See 
local address. See also network name. 

network addressable unit (NAU). In SNA, a logical unit, 
a physical unit, or a system services control point. It is 
the origin or the destination of information transmitted 
by the path control network. Each NAU has a network 
address that represents it to the path control network. 
See also network name, network address, and path 
control network. 

Network Communications Control Facility (NCCF). An 

IBM licensed program that is a base for command 
processors that can monitor, control, automate, and 
improve the operations of a network. Its function is 
included and enhanced in NetView's command facility. 

network control (NC). In SNA, an RU category used for 
requests and responses exchanged for such purposes 
as activating and deactivating explicit and virtual 
routes and sending load modules to adjacent periph- 



eral nodes. See also data flow control layer and 
session control. 

Network Control Program (NCP). An IBM licensed 
program that provides communication controller 
support for single-domain, multiple-domain, and inter- 
connected network capability. Its full name is 
Advanced Communications Function for the Network 
Control Program. 

network control program. A program, generated by 
the user from a library of IBM-supplied modules, that 
controls the operation of a communication controller. 

network log. A file that contains all messages proc- 
essed by the NetView program. 

network management vector transport (NMVT). A 

management services request/response unit (RU) that 
flows over an active session between physical unit 
management services and control point management 
services (SSCP-PU session). 

network name. (1) In SNA, the symbolic identifier by 
which end users refer to a network addressable unit 
(NAU), a link, or a link station. See also network 
address. (2) In a multiple-domain network, the name 
of the APPL statement defining a VTAM application 
program is its network name and it must be unique 
across domains. Contrast with ACB name. See unin- 
terpreted name. 

network operator. (1) A person or program respon- 
sible for controlling the operation of all or part of a 
network. (2) The person or program that controls all 
the domains in a multiple-domain network. Contrast 
with domain operator. 

network product support (NPS). The function of the 
NetView program that provides operations control for 
the IBM 3710 Network Controller, 5860 family of 
modems, and the NCP; and configuration of 3710s and 
the 5860 family of modems. NPS provides operator 
commands to run diagnostics for link problem determi- 
nation and to change product operating parameters. 

network services (NS). In SNA, the services within 
network addressable units (NAUs) that control network 
operation through SSCP-SSCP, SSCP-PU, and SSCP-LU 
sessions. See configuration services, maintenance 
services, management services, and session services. 

network services (NS) header. In SNA, a 3-byte field in 
a function management data (FMD) request/response 
unit (RU) flowing in an SSCP-LU, SSCP-PU, or 
SSCP-SSCP session. The network services header is 
used primarily to identify the network services category 
of the request unit (RU) (for example, configuration ser- 
vices, session services) and the particular request 
code within a category. 

NMVT. Network management vector transport. 



Glossary 327 



NNT. NetView-NetView task. 

node. (1) In SNA, an endpoint of a link or junction 
common to two or more links in a network. Nodes can 
be distributed to host processors, communication con- 
trollers, cluster controllers, or terminals. Nodes can 
vary in routing and other functional capabilities. See 
boundary node, host node, peripheral node, and 
subarea node (including illustration). (2) In VTAM, a 
point in a network defined by a symbolic name. See 
major node and minor node. 

node name. In VTAM, the symbolic name assigned to 
a specific major or minor node during network defi- 
nition. 

node type. In SNA, a designation of a node according 
to the protocols it supports and the network address- 
able units (NAUs) that it can contain. Five types are 
defined: 1, 2.0, 2.1, 4, and 5. Type 1, type 2.0, and type 
2.1 nodes are peripheral nodes; type 4 and type 5 
nodes are subarea nodes. See also type 2.1 node. 

no response. In SNA, a value in the 
form-of-response-requested field of the request header 
(RH) indicating that no response is to be returned to the 
request, whether or not the request is received and 
processed successfully. Contrast with definite 
response and exception response. 



operator station task (OST). The NetView task that 
establishes and maintains the online session with the 
network operator. There is one operator station task 
for each network operator who logs on to the NetView 
program. See NetView-NetView task. 

OST. Operator station task. 

pacing. In SNA, a technique by which a receiving com- 
ponent controls the rate of transmission of a sending 
component to prevent overrun or congestion. See 
session-level pacing, send pacing, and virtual route 
(VR) pacing. See also flow control. 

pacing response. In SNA, an indicator that signifies a 
receiving component's readiness to accept another 
pacing group; the indicator is carried in a response 
header (RH) for session-level pacing, and in a trans- 
mission header (TH) for virtual route pacing. 

page. (1) The portion of a panel that is shown on a 
display surface at one time. (2) To move back and 
forth among the pages of a multiple-page panel. See 
also scroll. (3) (ISO) In a virtual storage system, a 
fixed-length block that has a virtual address and that 
can be transferred between real storage and auxiliary 
storage. (4) To transfer instructions, data, or both 
between real storage and external page or auxiliary 
storage. 



NPS. Network product support. 

NS. Network services. 

online. Stored in a computer and accessible from a 
terminal. 

open. (1) In the IBM Token-Ring Network, to make an 
adapter ready for use. (2) A break in an electrical 
circuit. 

operand. (1) (ISO) An entity on which an operation is 
performed. (2) * That which is operated upon. An 
operand is usually identified by an address part of an 
instruction. (3) Information entered with a command 
name to define the data on which a command 
processor operates and to control the execution of the 
command processor. (4) An expression to whose 
value an operator is applied. See also definition state- 
ment, keyword, keyword parameter, and parameter. 

operator. (1) In a language statement, the lexical 
entity that indicates the action to be performed on oper- 
ands. (2) A person who operates a machine. See 
network operator. See also definition statement. 

operator profile. In the NetView program, the 
resources and activities a network operator has control 
over. The statements defining these resources and 
activities are stored in a file that is activated when the 
operator logs on. 



panel. (1) A formatted display of information that 
appears on a terminal screen. See also help panel and 
task panel. Contrast with screen. (2) In computer 
graphics, a display image that defines the locations and 
characteristics of display fields on a display surface. 

parameter. (1) (ISO) A variable that is given a con- 
stant value for a specified application and that may 
denote the application. (2) An item in a menu for 
which the user specifies a value or for which the 
system provides a value when the menu is interpreted. 
(3) Data passed to a program or procedure by a user 
or another program, namely as an operand in a lan- 
guage statement, as an item in a menu, or as a shared 
data structure. See also keyword, keyword parameter, 
and operand. 

partitioned data set (PDS). A data set in direct access 
storage that is divided into partitions, called members, 
each of which can contain a program, part of a 
program, or data. 

path. (1) In SNA, the series of path control network 
components (path control and data link control) that are 
traversed by the information exchanged between two 
network addressable units (NAUs). See also explicit 
route (ER), route extension, and virtual route (VR). 
(2) In VTAM when defining a switched major node, a 
potential dial-out port that can be used to reach that 
node. (3) In the NetView/PC program, a complete line 
in a configuration that contains all of the resources in 
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the service point command service (SPCS) query link 
configuration request list. 

path control (PC). The function that routes message 
units between network addressable units (NAUs) in the 
network and provides the paths between them. It con- 
verts the BlUs from transmission control (possibly seg- 
menting them) into path information units (PIUs) and 
exchanges basic transmission units (BTUs) and one or 
more PIUs with data link control. Path control differs 
for peripheral nodes, which use local addresses for 
routing, and subarea nodes, which use network 
addresses for routing. See peripheral path control and 
subarea path control. See also link, peripheral node, 
and subarea node. 

path control (PC) layer. In SNA, the layer that 
manages the sharing of link resources of the SNA 
network and routes basic information units (BlUs) 
through it. See also BIU segment, blocking of PIUs, 
data link control layer, and transmission control layer. 

path control (PC) network. In SNA, the part of the SNA 
network that includes the data link control and path 
control layers. See SNA network and user application 
network. See also boundary function. 



Personal Computer (PC). The IBM Personal Computer 
line of products including the 5150 and subsequent 
models. 

physical connection. In VTAM, a point-to-point con- 
nection or multipoint connection. Synonymous with 
connection. 

physical unit (PU). In SNA, a type of network address- 
able unit (NAU). A physical unit (PU) manages and 
monitors the resources (such as attached links) of a 
node, as requested by a system services control point 
(SSCP) through an SSCP-PU session. An SSCP acti- 
vates a session with the physical unit in order to indi- 
rectly manage, through the PU, resources of the node 
such as attached links. See also peripheral PU and 
subarea PU. 

physical unit (PU) services. In SNA, the components 
within a physical unit (PU) that provide configuration 
services and maintenance services for SSCP-PU ses- 
sions. See also logical unit (LU) services. 

PLU. Primary logical unit. 

POI. Programmed operator interface. 



PC. (1) Path control. (2) Personal Computer. Its full 
name is the IBM Personal Computer. 

peripheral host node. A node that provides an applica- 
tion program interface (API) for running application 
programs but does not provide SSCP functions and is 
not aware of the network configuration. The peripheral 
host node does not provide subarea node services. It 
has boundary function provided by its adjacent 
subarea. See boundary node, host node, node, periph- 
eral node, subarea host node, and subarea node. See 
also boundary function and node type. 

peripheral LU. In SNA, a logical unit representing a 
peripheral node. 

peripheral node. In SNA, a node that uses local 
addresses for routing and therefore is not affected by 
changes in network addresses. A peripheral node 
requires boundary-function assistance from an adja- 
cent subarea node. A peripheral node is a physical 
unit (PU) type 1, 2.0, or 2.1 node connected to a 
subarea node with boundary function within a subarea. 
See boundary node, host node, node, peripheral host 
node, subarea host node, and subarea node. See also 
boundary function and node type. 



positional operand. An operand in a language state- 
ment that has a fixed position. See also definition 
statement. Contrast with keyword operand. 

positive response. A response indicating that a 
request was received and processed. Contrast with 
negative response. 

POST. Power-on self test. A series of diagnostic tests 
that are run each time the computer's power is turned 
on. 

PPT. Primary POI task. 

primary half-session. In SNA, the half-session that 
sends the session activation request. See also primary 
logical unit. Contrast with secondary half-session. 

primary logical unit (PLU). In SNA, the logical unit (LU) 
that contains the primary half-session for a particular 
LU-LU session. Each session must have a PLU and 
secondary logical unit (SLU). The PLU is the unit 
responsible for the bind and is the controlling LU for 
the session. A particular LU may contain both primary 
and secondary half-sessions for different active LU-LU 
sessions. Contrast with secondary logical unit (SLU). 



peripheral path control. The function in a peripheral 
node that routes message units between units with 
local addresses and provides the paths between them. 
See path control and subarea path control. See also 
boundary function, peripheral node, and subarea node. 

peripheral PU. In SNA, a physical unit representing a 
peripheral node. 



primary POI task (PPT). The NetView subtask that 
processes all unsolicited messages received from the 
VTAM program operator interface (POI) and delivers 
them to the controlling operator or to the command 
processor. The PPT also processes the initial 
command specified to execute when the NetView 



Glossary 329 



program is initialized and timer request commands 
scheduled to execute under the PPT. 

problem determination. The process of identifying the 
source of a problem; for example, a program compo- 
nent, a machine failure, telecommunication facilities, 
user or contractor-installed programs or equipment, an 
environment failure such as a power loss, or a user 
error. 

product-set identification (PSID). (1) In SNA, a tech- 
nique for identifying the hardware and software pro- 
ducts that implement a network component. (2) A 
management services common subvector that trans- 
ports the information described in definition (1). 

profile. In the Conversational Monitor System (CMS) 
or the group control system (GCS), the characteristics 
defined by a PROFILE EXEC file that executes automat- 
ically after the system is loaded into a virtual machine. 
See also operator profile. 



record maintenance statistics (RECMS). An SNA error 
event record built from an NCP or line error and sent 
unsolicited to the host. 

reentrant. The attribute of a program or routine that 
allows the same copy of the program or routine to be 
used concurrently by two or more tasks. For example, 
the 3710 Network Controller routines may be reentrant. 

regular command. In the NetView program, any VTAM 
or NetView command that is not an immediate 
command and is processed by a regular command 
processor. Contrast with immediate command. 

release. For VTAM, to relinquish control of resources 
(communication controllers or physical units). See also 
resource takeover. Contrast with acquire (2). 

remote. Concerning the peripheral parts of a network 
not centrally linked to the host processor and generally 
using telecommunication lines with public right-of-way. 



programmed operator interface (POI). A VTAM func- 
tion that allows programs to perform VTAM operator 
functions. 

PSID. Product-set identification. 

PU. Physical unit. 

public network. A network established and operated 
by communication common carriers or telecommuni- 
cation Administrations for the specific purpose of pro- 
viding circuit-switched, packet switched, and 
leased-circuit services to the public. Contrast with 
user-application network. 

PU-PU flow. In SNA, the exchange between physical 
units (PUs) of network control requests and responses. 

receive pacing. In SNA, the pacing of message units 
that the component is receiving. See also send pacing. 

RECFMS. Record formatted maintenance statistics. 



remove. In the IBM Token-Ring Network, to take an 
attaching device off the ring. 

request header (RH). In SNA, control information pre- 
ceding a request unit (RU). See also request! response 
header (RH). 

request unit (RU). In SNA, a message unit that con- 
tains control information, end-user data, or both. 

request/response header (RH). In SNA, control infor- 
mation, preceding a request/response unit (RU), that 
specifies the type of RU (request unit or response unit) 
and contains control information associated with that 
RU. 

request/response unit (RU). In SNA, a generic term for 
a request unit or a response unit. See also request unit 
(RU) and response unit. 

reset. On a virtual circuit, reinitialization of data flow 
control. At reset, all data in transit are eliminated. 



RECMS. Record maintenance statistics. 

record. (1) (ISO) In programming languages, an 
aggregate that consists of data objects, possibly with 
different attributes, that usually have identifiers 
attached to them. In some programming languages, 
records are called structures. (2) (TC97) A set of data 
treated as a unit. (3) A set of one or more related data 
items grouped for processing. (4) In VTAM, the unit of 
data transmission for record mode. A record repres- 
ents whatever amount of data the transmitting node 
chooses to send. 

record formatted maintenance statistics (RECFMS). A 

statistical record built by an SNA controller and usually 
solicited by the host. 



resource. (1) Any facility of the computing system or 
operating system required by a job or task, and 
including main storage, input/output devices, the proc- 
essing unit, data sets, and control or processing pro- 
grams. (2) In the NetView program, any hardware or 
software that provides function to the network. 

resource takeover. In VTAM, action initiated by a 
network operator to transfer control of resources from 
one domain to another. See also acquire (2) and 
release. See takeover. 

response. A reply represented in the control field of a 
response frame. It advises the primary or combined 
station of the action taken by the secondary or other 
combined station to one or more commands. See also 
command. 
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response header (RH). In SNA, a header, optionally 
followed by a response unit (RU), that indicates 
whether the response is positive or negative and that 
may contain a pacing response. See also negative 
response, pacing response, and positive response. 

response time. (1) The amount of time it takes after a 
user presses the enter key at the terminal until the 
reply appears at the terminal. (2) For response time 
monitoring, the time from the activation of a transaction 
until a response is received, according to the response 
time definition coded in the performance class. 

response unit (RU). In SNA, a message unit that 
acknowledges a request unit; it may contain prefix 
information received in a request unit. If positive, the 
response unit may contain additional information (such 
as session parameters in response to Bind Session), or 
if negative, contains sense data defining the exception 
condition. 

Restructured Extended Executor (REXX). An interpre- 
tive language used to write command lists. 

return code. * A code [returned from a program] used 
to influence the execution of succeeding instructions. 

REXX. Restructured Extended Executor. 

RH. Request/response header. 

route. See explicit route and virtual route. 

route extension (REX). In SNA, the path control 
network components, including a peripheral link, that 
make up the portion of a path between a subarea node 
and a network addressable unit (NAU) in an adjacent 
peripheral node. See also path, explicit route (ER) and 
virtual route (VR). 

routing. The assignment of the path by which a 
message will reach its destination. 

RPL exit routine. In VTAM, an application program exit 
routine whose address has been placed in the EXIT 
field of a request parameter list (RPL). VTAM invokes 
the routine to indicate that an asynchronous request 
has been completed. See EXLSTexit routine. 

RU. Request/response unit. 

RU chain. In SNA, a set of related request/response 
units (RUs) that are consecutively transmitted on a par- 
ticular normal or expedited data flow. The request RU 
chain is the unit of recovery: if one of the RUs in the 
chain cannot be processed, the entire chain is dis- 
carded. Each RU belongs to only one chain, which has 
a beginning and an end indicated by means of control 
bits in request/response headers within the RU chain. 
Each RU can be designated as first-in-chain (FIC), 
last-in-chain (LIC), middle-in-chain (MIC), or 



only-in-chain (OIC). Response units and expedited-flow 
request units are always sent as only-in-chain. 

scope of commands. In the NetView program, the 
facility that provides the ability to assign different 
responsibilities to various operators. 

screen. An illuminated display surface; for example, 
the display surface of a CRT or plasma panel. Contrast 
with panel. 

scroll. To move all or part of the display image verti- 
cally to display data that cannot be observed within a 
single display image. See also page (2). 

secondary half-session. In SNA, the half-session that 
receives the session-activation request. See also sec- 
ondary logical unit (SLU). Contrast with primary 
half-session. 

secondary logical unit (SLU). In SNA, the logical unit 
(LU) that contains the secondary half-session for a par- 
ticular LU-LU session. An LU may contain secondary 
and primary half-sessions for different active LU-LU 
sessions. Contrast with primary logical unit (PLU). 

secondary logical unit (SLU) key. A key-encrypting key 
used to protect a session cryptography key during its 
transmission to the secondary half-session. 

send pacing. In SNA, pacing of message units that a 
component is sending. See also receive pacing. 

sequence number. A number assigned to a particular 
frame or packet to control the transmission flow and 
receipt of data. 

service point (SP). An entry point that supports appli- 
cations that provide network management for 
resources not under the direct control of itself as an 
entry point. Each resource is either under the direct 
control of another entry point or not under the direct 
control of any entry point. A service point accessing 
these resources is not required to use SNA sessions 
(unlike a focal point). A service point is needed when 
entry point support is not yet available for some 
network management function. 

service point command service (SPCS). An extension 
of the command facility in the NetView program that 
allows the host processor to communicate with a 
service point by using the communication network 
management (CNM) interface. 

session. In SNA, a logical connection between two 
network addressable units (NAUs) that can be acti- 
vated, tailored to provide various protocols, and deacti- 
vated, as requested. Each session is uniquely 
identified in a transmission header (TH) by a pair of 
network addresses, identifying the origin and destina- 
tion NAUs of any transmissions exchanged during the 
session. See half-session, LU-LU session, SSCP-LU 
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session, SSCP-PU session, and SSCP-SSCP session. 
See also LU-LU session type and PU-PU flow. 

session control (SC). In SNA, (1) One of the compo- 
nents of transmission control. Session control is used 
to purge data flowing in a session after an unrecover- 
able error occurs, to resynchronize the data flow after 
such an error, and to perform cryptographic verifica- 
tion. (2) A request unit (RU) category used for requests 
and responses exchanged between the session control 
components of a session and for session activation and 
deactivation requests and responses. 

session-initiation request. In SNA, an Initiate or logon 
request from a logical unit (LU) to a control point (CP) 
that an LU-LU session be activated. 

session-level pacing. In SNA, a flow control technique 
that permits a receiver to control the data transfer rate 
(the rate at which it receives request units) on the 
normal flow. It is used to prevent overloading a 
receiver with unprocessed requests when the sender 
can generate requests faster than the receiver can 
process them. See also pacing and virtual route 
pacing. 

session monitor. The component of the NetView 
program that collects and correlates session-related 
data and provides online access to this information. 

session services. In SNA, one of the types of network 
services in the control point (CP) and in the logical unit 
(LU). These services provide facilities for an LU or a 
network operator to request that the SSCP initiate or 
terminate sessions between logical units. See config- 
uration services, maintenance services, and manage- 
ment services. 

shared. Pertaining to the availability of a resource to 
more than one use at the same time. 

simulated logon. A session-initiation request gener- 
ated when a VTAM application program issues a 
SIMLOGON macroinstruction. The request specifies a 
logical unit (LU) with which the application program 
wants a session in which the requesting application 
program will act as the primary logical unit (PLU). 

single-domain network. In SNA, a network with one 
system services control point (SSCP). Contrast with 
multiple-domain network. 

SLU. Secondary logical unit. 

SMF. System management facility. 

SNA. Systems Network Architecture. 

SNA network. The part of a user-application network 
that conforms to the formats and protocols of Systems 
Network Architecture. It enables reliable transfer of 
data among end users and provides protocols for con- 



trolling the resources of various network configura- 
tions. The SNA network consists of network 
addressable units (NAUs), boundary function compo- 
nents, and the path control network. 

SP. Service point. 

SPCS. Service point command service. 

span. In the NetView program, a user-defined group of 
network resources within a single domain. Each major 
or minor node is defined as belonging to one or more 
spans. See also span of control. 

span of control. The total network resources over 
which a particular network operator has control. All 
the network resources listed in spans associated 
through profile definition with a particular network 
operator are within that operator's span of control. 

SSCP. System services control point. 

SSCP-LU session. In SNA, a session between a 
system services control point (SSCP) and a logical unit 
(LU); the session enables the LU to request the SSCP to 
help initiate LU-LU sessions. 

SSCP-PU session. In SNA, a session between a 
system services control point (SSCP) and a physical 
unit (PU); SSCP-PU sessions allow SSCPs to send 
requests to and receive status information from indi- 
vidual nodes in order to control the network configura- 
tion. 

SSCP-SSCP session. In SNA, a session between the 
system services control point (SSCP) in one domain 
and the SSCP in another domain. An SSCP-SSCP 
session is used to initiate and terminate cross-domain 
LU-LU sessions. 

SSP. System Support Programs (IBM licensed 
program). Its full name is Advanced Communications 
Function for System Support Programs. Synonymous 
with ACF/SSP. 

start option. In VTAM, a user-specified or 
IBM-supplied option that determines certain conditions 
that are to exist during the time a VTAM system is 
operating. Start options can be predefined or specified 
when VTAM is started. 

statement. A language syntactic unit consisting of an 
operator, or other statement identifier, followed by one 
or more operands. See definition statement. 

station. (1) One of the input or output points of a 
network that uses communication facilities; for 
example, the telephone set in the telephone system or 
the point where the business machine interfaces with 
the channel on a leased private line. (2) One or more 
computers, terminals, or devices at a particular 
location. 
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subarea. A portion of the SNA network consisting of a 
subarea node, any attached peripheral nodes, and their 
associated resources. Within a subarea node, all 
network addressable units, links, and adjacent link 
stations (in attached peripheral or subarea nodes) that 
are addressable within the subarea share a common 
subarea address and have distinct element addresses. 

subarea host node. A host node that provides both 
subarea function and an application program interface 
(API) for running application programs. It provides 
system services control point (SSCP) functions, 
subarea node services, and is aware of the network 
configuration. See boundary node, communication 
management configuration host node, data host node, 
host node, node, peripheral node, and subarea node. 
See also boundary function and node type. 

subarea node. In SNA, a node that uses network 
addresses for routing and whose routing tables are 
therefore affected by changes in the configuration of 
the network. Subarea nodes can provide gateway func- 
tion, and boundary function support for peripheral 
nodes. Type 4 and type 5 nodes are subarea nodes. 
See boundary node, host node, node, peripheral node, 
and subarea host node. See also boundary function 
and node type. 

subarea path control. The function in a subarea node 
that routes message units between network address- 
able units (NAUs) and provides the paths between 
them. See path control and peripheral path control. 
See also boundary function, peripheral node, and 
subarea node. 



system services control point (SSCP) domain. The 

system services control point and the physical units 
(PUs), logical units (LUs), links, link stations and all the 
resources that the SSCP has the ability to control by 
means of activation requests and deactivation 
requests. 

Systems Network Architecture (SNA). The description 
of the logical structure, formats, protocols, and opera- 
tional sequences for transmitting information units 
through and controlling the configuration and operation 
of networks. 

System Support Programs (SSP). An IBM licensed 
program, made up of a collection of utilities and small 
programs, that supports the operation of the NCP. 

TAF. Terminal access facility. 

takeover. The process by which the failing active sub- 
system is released from its extended recovery facility 
(XRF) sessions with terminal users and replaced by an 
alternate subsystem. See resource takeover. 

task. A basic unit of work to be accomplished by a 
computer. The task is usually specified to a control 
program in a multiprogramming or multiprocessing 
environment. 

task panel. Online display from which you communi- 
cate with the program in order to accomplish the pro- 
gram's function, either by selecting an option provided 
on the panel or by entering an explicit command. See 
help panel. 



subarea PU. In SNA, a physical unit (PU) in a subarea 
node. 

subsystem. A secondary or subordinate system, 
usually capable of operating independent of, or asyn- 
chronously with, a controlling system. 

subvector. A subcomponent of the MAC major vector. 



telecommunication line. Any physical medium such as 
a wire or microwave beam, that is used to transmit 
data. Synonymous with transmission line. 

terminal. A device that is capable of sending and 
receiving information over a link; it is usually equipped 
with a keyboard and some kind of display, such as a 
screen or a printer. 



supervisor. The part of a control program that coordi- 
nates the use of resources and maintains the flow of 
processing unit operations. 

system management facility (SMF). A standard feature 
of MVS that collects and records a variety of system 
and job-related information. 

system services control point (SSCP). In SNA, a 
central location point within an SNA network for man- 
aging the configuration, coordinating network operator 
and problem determination requests, and providing 
directory support and other session services for end 
users of the network. Multiple SSCPs, cooperating as 
peers, can divide the network into domains of control, 
with each SSCP having a hierarchical control relation- 
ship to the physical units and logical units within its 
domain. 



terminal access facility (TAF). In the NetView 
program, a facility that allows a network operator to 
control a number of subsystems. In a full-screen or 
operator control session, operators can control any 
combination of such subsystems simultaneously. 

TERMINATE. In SNA, a request unit that is sent by a 
logical unit (LU) to its system services control point 
(SSCP) to cause the SSCP to start a procedure to end 
one or more designated LU-LU sessions. 

time-out. (1) (ISO) An event that occurs at the end of 
a predetermined period of time that began at the occur- 
rence of another specified event. (2) A time interval 
allotted for certain operations to occur; for example, 
response to polling or addressing before system opera- 
tion is interrupted and must be restarted. 
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time sharing option (TSO). An optional configuration of 
the operating system that provides conversational time 
sharing from remote stations. 

token. A sequence of bits passed from one device to 
another along the token ring. When the token has data 
appended to it, it becomes a frame. 

transmission control (TC) layer. In SNA, the layer 
within a half-session that synchronizes and paces 
session-level data traffic, checks session sequence 
numbers of requests, and enciphers and deciphers 
end-user data. Transmission control has two compo- 
nents: the connection point manager and session 
control. See also half-session. 

transmission line. Synonym for telecommunication 
line. 

TSO. Time sharing option. 

type 2.1 node (T2.1 node). A node that can attach to an 
SNA network as a peripheral node using the same pro- 
tocols as type 2.0 nodes. Type 2.1 nodes can be 
directly attached to one another using peer-to-peer pro- 
tocols. See end node, node, and subarea node. See 
also node type. 

type 2.1 node (T2.1 node) control point domain. The 

CP, its logical units (LUs), links, link stations, and all 
resources that it activates and deactivates. 



user. Anyone who requires the services of a com- 
puting system. 

user-application network. A configuration of data proc- 
essing products, such as processors, controllers, and 
terminals, established and operated by users for the 
purpose of data processing or information exchange, 
which may use services offered by communication 
common carriers or telecommunication Adminis- 
trations. Contrast with public network. 

user exit. A point in an IBM-supplied program at which 
a user routine may be given control. 

user exit routine. A user-written routine that receives 
control at predefined user exit points. User exit rou- 
tines can be written in assembler or a high-level lan- 
guage (HLL). 

USS. Unformatted system services. 

value. (1) (TC97) A specific occurrence of an attri- 
bute, for example, "blue" for the attribute "color." (2) A 
quantity assigned to a constant, a variable, a param- 
eter, or a symbol. 

variable. In the NetView program, a character string 
beginning with & that is coded in a command list and is 
assigned a value during execution of the command list. 

vector. The MAC frame information field. 



unformatted. In VTAM, pertaining to commands (such 
as LOGON or LOGOFF) entered by an end user and 
sent by a logical unit in character form. The 
character-coded command must be in the syntax 
defined in the user's unformatted system services defi- 
nition table. Synonymous with character-coded. Con- 
trast with field-formatted. 

unformatted system services (USS). In SNA products, 
a system services control point (SSCP) facility that 
translates a character-coded request, such as a logon 
or logoff request into a field-formatted request for proc- 
essing by formatted system services and translates 
field-formatted replies and responses into 
character-coded requests for processing by a logical 
unit. Contrast with formatted system services. See 
also converted command. 

uninterpreted name. In SNA, a character string that a 
system services control point (SSCP) is able to convert 
into the network name of a logical unit (LU). Typically, 
an uninterpreted name is used in a logon or Initiate 
request from a secondary logical unit (SLU) to identify 
the primary logical unit (PLU) with which the session is 
requested. 

upstream. In the direction of data flow from the end 
user to the host. Contrast with downstream. 



verb. (1) In SNA, the general name for a transaction 
program's request for communication services. (2) In 
VTAM, a programming language element in the logical 
unit (LU) 6.2 application program interface (API) that 
causes an LU 6.2 function to be performed. 

Virtual Machine (VM). A licensed program whose full 
name is the Virtual Machine/System Product (VM/SP). 
It is a software operating system that manages the 
resources of a real processor to provide virtual 
machines to end users. As a time-sharing system 
control program, it consists of the virtual machine 
control program (CP), the conversational monitor 
system (CMS), the group control system (GCS), and the 
interactive problem control system (IPCS). 

virtual route (VR). In SNA, a logical connection (1) 
between two subarea nodes that is physically realized 
as a particular explicit route, or (2) that is contained 
wholly within a subarea node for intranode sessions. A 
virtual route between distinct subarea nodes imposes a 
transmission priority on the underlying explicit route, 
provides flow control through virtual-route pacing, and 
provides data integrity through sequence numbering of 
path information units (PIUs). See also explicit route 
(ER), path, and route extension. 

virtual route (VR) pacing. In SNA, a flow control tech- 
nique used by the virtual route control component of 
path control at each end of a virtual route to control the 
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rate at which path information units (PIUs) flow over the 
virtual route. VR pacing can be adjusted according to 
traffic congestion in any of the nodes along the route. 
See also pacing and session-level pacing. 

virtual route selection exit routine. In VTAM, an 
optional installation exit routine that modifies the list of 
virtual routes associated with a particular class of 
service before a route is selected for a requested 
LU-LU session. 

virtual storage. (ISO) The notion of storage space that 
may be regarded as addressable main storage by the 
user of a computer system in which virtual addresses 
are mapped into real addresses. The size of virtual 
storage is limited by the addressing scheme of the 
computer system and by the amount of auxiliary 
storage available, not by the actual number of main 
storage locations. 

Virtual Storage Access Method (VSAM). An access 
method for direct or sequential processing of fixed and 
variable-length records on direct access devices. The 
records in a VSAM data set or file can be organized in 
logical sequence by a key field (key sequence), in the 
physical sequence in which they are written on the data 
set or file (entry-sequence), or by relative-record 
number. 

Virtual Storage Extended (VSE). An IBM licensed 
program whose full name is the Virtual Storage 
Extended/Advanced Function. It is a software oper- 
ating system controlling the execution of programs. 

Virtual Telecommunications Access Method (VTAM). 

An IBM licensed program that controls communication 
and the flow of data in an SNA network. It provides 
single-domain, multiple-domain, and interconnected 
network capability. 

vital product data. Product identification information 
such as machine type, model number, and serial 



number for hardware products. For software products, 
vital product data can be version and release level. 

VM. Virtual Machine operating system. Its full name is 
Virtual Machine/System Product. Synonymous with 
VM/SP. 

VM SNA console support (VSCS). A VTAM component 
for the VM environment that provides Systems Network 
Architecture (SNA) support. It allows SNA terminals to 
be virtual machine consoles. 

VM/SP. Virtual Machine/System Product operating 
system. Synonym for VM. 

VR. Virtual route. 

VSAM. Virtual Storage Access Method. 

VSCS. VM SNA console support. 



VSE. Virtual Storage Extended operating system, 
onymous with VSE/AF. 



Syn- 



VSE/AF. Virtual Storage Extended/Advanced Function 
operating system. Synonym for VSE. 

VTAM. Virtual Telecommunications Access Method 
(IBM licensed program). Its full name is Advanced 
Communications Function for the Virtual Telecommuni- 
cations Access Method. Synonymous with ACF/VTAM. 

VTAM operator command. A command used to 
monitor or control a VTAM domain. See also definition 
statement. 

wrap. In general, to go from the maximum to the 
minimum in computer storage. For example, the con- 
tinuation of an operation from the maximum value in 
storage to the first minimal value. 
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of the functions of the F-keys throughout the 
NetView/PC program. 



Other Network Program 
Products Publications 

For more information about the books listed in this 
section, see Bibliography and Master Index for 
NetView, NCP, and VTAM. 



Network Program Products General Information 
(GC30-3350) 

Network Program Products Planning (SC30-3351) 

Network Program Products Samples (SG30-3352) 

Bibliography and Master Index for NetView, NCP, and 
VTAM (GC31 -6081)2 

VTAM Publications 

The following list shows the books for vtam V3R2. For 
information about the books for vtam V3R1, V3R1.1, or 
V3R1.2, see any vtam V3R2 book or the Network Program 
Products Bibliography and Master Index. 
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concatenated 9 
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end-of-file 18 

event 186 

EWCCMDSO 

See STDERR 
EWCCSIN0 

See STDIN 
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See STDOUT 
EXCMD command 236 
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EXTLOG parameter 19 
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FILE option 35 

first failure data capture trace (FFDCT) 8 
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format-string parameter 99 
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FREE command 6, 34, 102 

full-screen input/output 5 
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gdqueue parameter 207 
GET statement 35 
getchar routine 103 
GETDATA function 40,114 
global user exit routines 9 

DSIEX01 12 

DSIEX02A 12 

DSIEX03 12 

DSIEX04 13 

DSIEX05 13 

DSIEX06 14 

DSIEX07 14 

DSIEX09 14 

DSIEX10 14 

DSIEX11 15 

DSIEX12 15 

DSIEX13 15 

DSIEX14 16 

DSIEX16 16 
GO command 4, 40, 53, 114, 130, 177, 207 

H 

HAPIENTR 171 

HAPIEXIT 171 

hardcopy device name (function) 15 

hardcopy log 13, 209 

HDRMTYPE field 195 

HDRTYPEX cross-domain 11 

HDRTYPEX message 12 

HEAP size 29, 92 

HEAPSIZ 28, 171 

hex conversion 101 

hexadecimal value 231 

HLB control block 36, 104 

HLBLENG 204, 207, 210, 213, 220, 239 

HLBPRT 171 

HLBPTR 27, 91 

HLBRC 10, 174 

HLBRC field 36,104 

HLL C constants 280 

HLL C mapping of DSIHLB 285 

HLL C return codes 292 

HLL C service routine definitions 288 

HLL C varying length character strings 284 

HLL command processors 
considerations for 36, 103 
created with KnowledgeTool 77 



HLL commands 
GO 177 
overview of 177 
QUEUE 179 
RESET 180 
TRAP 183 
WAIT 186 
WAIT CONTINUE 187 

HLL PL/I constants 246 

HLL PL/I mapping of DSIHLB 250 

HLL PL/I origin block mapping 252, 287 

HLL PL/I return codes 260 

HLL procedure invoking 46, 117 

HLL programs written in C 
restrictions 104 

HLL programs written in PL/I 
restrictions 36 

HLL run-time options 27, 91 

HLL service routines 

CNMALTD (CNMALTDATA) 190 
CNMCELL (CNMSTRCELL) 193 
CNMCMD (CNMCOMMAND) 195 
CNMCNMI (CNMI) 199 
CNMCPYS (CNMCOPYSTR) 201 
CNMGETA (CNMGETATTR) 203 
CNMGETD (CNMGETDATA) 206 
CNMINFC (CNMINFOC) 209 
CNMINFI (CNMINFOI) 211 
CNMKIO (CNMKEYIO) 213 
CNMLK (CNMLOCK) 216 
CNMMEMC (CNMCLOSMEM) 222 
CNMMEMO (CNMOPENMEM) 218 
CNMMEMR (CNMREADMEM) 220 
CNMNAMS (CNMNAMESTR) 223 
CNMPOOL (CNMSTRPOOL) 226 
CNMSCAN (CNMSSCAN) 229 
CNMSCOP (CNMSCOPECK) 232 
CNMSMSG (CNMSENDMSG) 234 
CNMVARS (CNMVARPOOL) 238 
overview of 190 

HLL user exit routines 

HLLOPTS 179 

HLLOPTS variable 92 

HLL_NO_CANCEL field 28, 92 

HLL_QUEUED_INPUT 179 

HLL QUEUED INPUT field 28, 92 



icdata parameter 210 
icdatlen parameter 210 
icname parameter 209 
IDATAQ 40, 60, 114, 139, 207 
IFRCODUS 15 
iiname parameter 211 
iinumb parameter 212 
immediate command 36, 103 
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immediate commands 195 

initial command 12 

initial data queue 40, 114, 191, 203, 207 

initial data queue (IDATAQ) 204 

initial parameters 27, 91 

input before command processing 12 

input from the operator 12 

input from the system console 14 

integer variables in C, using 95 

integer variables in PL/I, using 32 

internal function request (IFR) 15 

IRB exit environment 10 

ISA size 29, 92 

ISAINC run-time option 92 

ISASIZ 28, 171 

ISASIZE run-time option 92 

istring parameter 99, 101 

K 

Kanjii 12 

key-sequenced data set (KSDS) 19 

key-sequenced VSAM files 213 

keyword 232 

knowledge applications 

developing 81 

sample 77 

within NetView 77 
knowledge routines 

See system extensions 
KnowledgeTool 

commands 
KTCOMP 77 
KTLINK 77 
KTRUN 77 

debugger 81 

sample 78 

within NetView 

See knowledge applications 
KTCOMP command 77 
KTLINK 81 
KTLINK command 77 
KTRUN command 77 



label line message 234 
line mode output 4 
link-edit JCL 163 
Ikfunc parameter 216 
Ikname parameter 216 
Ikoption parameter 216 
Ikscope parameter 216 
local pool 

of calling command procedure or HLL user exit 
routine 239 

of current HLL command processor or user exit 
routine 239 



lock management 7 
log output 11,13 
logical unit name 209 
logoff 11 

LOGOFF command 16 
LOGOFF routine 21 1 
logon validation 11,15 
long running command 195 
LOSTERM exit 16 

M 

macro library 163 
main HLL C include file 279 
main HLL PL/I include file 245 
major vector 17 
MAPCL command 77 
mctoken parameter 222 
member name 218 
message 

automation 5, 12, 13, 14, 15, 207 

logging 7 

multi-line 4, 5 

translated 12 

trapping 5 
message automation 40, 56, 77, 114, 134, 191 
message identifier 204 
message output 11 
message processing 56, 134 
message queue (TRAPQ) 183 
message queues 40,114 
message receiver 11 
message text 204 
messages 186 
moddname parameter 218 
momemnam parameter 218 
motoken parameter 218 
mrdata parameter 220 
mrdatlen parameter 220 
mrtoken parameter 220 
multi-line messages 206 

multi-line write-to-operator (MLWTO) line type 204 
multiple line messages 56, 134 
MVS console 12 
MVS console operator task 15 
MVS JOB name 203 
MVS JOB number 203 
MVS system 204 
MVS system log 13 
MVTCLOSE 211 
MVTUFLD 211 

N 

named storage 7 

negative response 199 

NetView command list language 42, 239 
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NetView command list language variables 

&HDRMTYPE 204 

&LINETYPE 204 

&MSGID 204 

&MSGORIGIN 204 

&MSGSTR 204 
NetView data sets 64, 143 
NetView domain ID 209 
NetView message type 204 
NetView start time 209 
NetView version and release 209 
network log 13, 235 
new password (function) 15 
NMVT 17, 66, 145 
NNT 11, 14,15 
NOHEXCNV 99, 101 
non-cancellable 28, 92 
NORENT variable 92 
NOSPIE option 29, 35, 104 
NOSPIE run-time option 92 
NOSTAE option 29, 35, 104 
NOSTAE run-time option 92 
notational conventions 

braces 173 

brackets 173 

lowercase 173 

OR sign | 173 

underscored 173 

uppercase 173 
nsclass parameter 223 
nsfunc parameter 223 
nsleng parameter 223 
nsname parameter 223 
nsptr parameter 223 
null character (\0) 96 
null terminator 99, 101 

o 

ON CYCLE blocks 77 

ON ENTRY blocks 77, 78 

ON FIXEDOVERFLOW 36 

ON IDLE blocks 77, 78 

ON IDLE ENTRY 78 

ON OVERFLOW 36 

ON UNDEFINEDFILE statement 34 

ON UNDERFLOW 36 

ON ZERODIVIDE 36 

ON-UNIT statement 35 

open capability 64, 143 

operating system 209 

operator ID 209, 232 

operator ID name (function) 15 

operator input 53, 130, 186, 187, 211 

operator input queue (OPERQ) 179 

operator LU name (function) 15 

operator station tasks (OST) 47, 118 



operator terminal 209 
operators in group 235 
OPERQ 40,114,207 
OPINPUT 53, 130, 177, 186 
ORIGBLCK 27,91,171 
origin block 33,96,191,207 
origin block (ORIGBLCK) 33, 96 
OST 11,15 

OST/NNT message receiver 15 
output to the operator 12 
output to the system console 14 

P 

P indicator 187 
PACTLU 267 

pafield1,...,pafield10 parameter 229 
panumfld parameter 229 
parameters passed to HLL service routines (HLL 
service routine parameters) 
fixed length character strings 33, 96 
integer variables 32, 95 
pointer variables 30, 93 
varying length character strings 33, 97 
parsing character strings 7 
parsing input strings 

like NetView command list language 42 
like REXX 43 
PL/I 44 
password (function) 15 
pastring parameter 229 
pattern parameter 229 
PAUSE 177 
pcfunc parameter 193 
PCNMI 266 
pcstrptr parameter 193 
pctoken parameter 193 
PDOVSAM 267 
performance 16 
period of time 186 
PEXIT2A 266, 269 
PEXIT3 265 
PFLVIEW 267 
PKEYIO 266 
PLIOPTS 28, 171 
PLIRETC 36 
PLIRETV 36 

PL/I commands and service routines 
examples of 

altering data 60 

CNMI 65 

command list variable access 51 

data queue management 40 

data set access 64 

DSIEX03 user exit 72 

DST user exit 71 

message processing 56 

operator input 53 

parsing input strings 42—45 
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46 



69 



PL/I commands and service routines (continued) 
examples of (continued) 
retrieving information 50 
scope checking 57 
sending commands 47 
sending information 41 
storage access 62 
synchronous commands 
using locks 52 
VIEW 54 

VSAM (keyed file access) 
wait for data 73 
waiting and trapping 48 
PL/I control blocks and include files 34 
DSIPCNM 260 
DSIPCONS 246 
DSIPHLB 250 
DSIPHLLS 253 
DSIPLI 245 
DSIPORIG 252 
PL/I definitions for HLL service routines 253 
PL/I error conditions 35 
PL/I I/O considerations 34 
PL/I module, coding 
interfaces 27 
restrictions 27 
PL/I run-time considerations 35 
PL/I run-time options 28 
PL/I sample template 37 
PL/I samples 
descriptions 

PACTLU (CNMS4218) 267 
PCNMI (CNMS4214) 266 
PDOVSAM (CNMS4223) 267 
PEXIT2A (CNMS4213) 266, 269 
PEXIT3(CNMS4210) 265 
PFLVIEW (CNMS4217) 267 
PKEYIO (CNMS4215) 266 
PPRIME (CNMS4224) 268 
PSCOPCK (CNMS4216) 266, 272 
PSEQLOG (CNMS4219) 267, 276 
PSNDDAT (CNMS421 1 ) 265 
PSNDDST (CNMS4222) 267 
PTMPPLT (CNMS4200) 265 
PWATDAT (CNMS4212) 265 
PXITDI (CNMS4220) 267 
PXITVN (CNMS4221) 267 
example of 

DSIEX02A 269 
scope checking 272 
sequential logging 276 
how to access 263 
table of 264 
POI 13, 15 

pointer variables in C, using 94 
pointer variables in PL/I, using 31 
post-message automation table exit 16 



PPRIME 268 

PPT 11,235 

pragma 92 

primary POI task (PPT) 47,118 

printf function 99 

process ID 209 

profile name (function) 15 

PSCOPCK 266, 272 

PSEQLOG 267, 276 

pseudo-synchronously 4 

PSNDDAT 265 

PSNDDST 267 

PTMPPLT 265 

PU name 199 

PUT statement 35 

putchar routine 103 

PWATDAT 265 

PXITDI 267 

PXITVN 267 

Q 

QUEUE command 40, 114, 179, 207 
queue of messages 184 

R 

read capability 64, 143 
RECFMS 17 
RECMS 17 
reentrant 163 
regular command 12 

remote interactive debugger (RID) 8, 28, 167 
replacing messages 10 
reply identifier 203 
reply RU 199 
REPORT option 92 
RESET 212 
RESET command 180 
RETCODE 171 

retrieving information 50, 123 
return code field (HLBRC) 36, 104 
return codes 10, 36, 104 
REXX 239 
RH header 199 
RID 8, 171 

RID command 167, 169 
options 

CONTINUE 168 

END 168 

MODNAME 168 

OPTION 168 

RUN 168 

STEP 167 
RID scenarios 169 
RID, using 167 
ROUTE-INOP 17 
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RU 17, 18 
RULE 78 
rules 77 
run-time libraries 



164 



sccmd parameter 232 
sckwd parameter 232 
scope checking 7, 57, 136 
scope class 57, 136 
scvalue parameter 232 
see = ' 174,175 
SEND side 75,160 
sending commands 47,118 
sending information 41,115 
sending messages 41, 115 
sequential log 235 

serial number of the screen update 212 
serialize access 216 
signal function 104 
simulated terminal input 12 
single line message 234 
smdestid parameter 235 
smdestyp parameter 235 
smmsgtyp 186, 209 
smmsgtyp parameter 234 
smtext parameter 234 
solicited VTAM messages 14 
span checking 13 
spclass parameter 226 
spfunc parameter 226 
SPIE option 35, 104 
spleng parameter 226 
spname parameter 226 
sppricnt parameter 226 
spseccnt parameter 226 
sptoken parameter 226 
SSCANF 44 
STAE option 35, 104 
standard error device 

See STDERR 
standard input device 

See STDIN 
standard output device 

See STDOUT 
STCK instruction 209, 210 
STDERR 81,104 
STDIN 81,103 
STDOUT 81, 103 
storage access 62, 141 
storage cell 227 
storage copying 6 

storage overlay 204, 207, 210, 220, 239 
storage pool 6, 227 

allocate 226 

free 226 

locate 226 



string 231 

synchronous command execution 3 

synchronous commands 46, 117 

synonyms 14 

SYSCONID 203 

SYSIN 35 

SYSPRINT 35 

SYSPRINT file 35 

system ABEND 213 35,103 

system console 11, 235 

system extensions 

See also STDIN, STDOUT, STDERR 
example of 

standard error system extension 85 
standard input system extension 82 
standard output system extension 84 

system message flags 203 

system message type 203 

system routing code 203 

SYS1.LINKLIB 163 

SYS1.MACLIB 163 

SYS1.NVULIB 163 



TAF session ID 203 

task global 238, 239 

task global pool 240 

task global variable 72, 155 

taskglobals 51,125 

task name 210 

terminating 211 

TIBSCRSN control block 212 

token 183, 193, 218, 220 

TRAP 48, 120 

TRAP command 40, 114, 183, 186, 207 

TRAP NO MESSAGES 184 

TRAPQ 40,114,184,207 

TVBABEND 211 

TVBLOGOF 211 

TVBPAUSE 211 

TVBRESET 212 

u 

unattended operator task 15 
unsolicited VTAM messages 15 
user exit 34, 71 , 72, 102, 153, 155, 212 
user exit routine 199, 214 
user exit routines 10 

purpose of 9 

return codes 10 

types 

DST user exit routines 9 
global user exit routines 9 
user exits 164 
USERASIS 10 
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USERBINT 212 

USERBOUT 212 

USERCINP 212 

USERCOUT 212 

USERDINT 212 

USERDROP 9, 10 

USERHCL 13 

USERHCLR 13 

USERLOG 13 

USERLOGR 13 

USERSWAP 10 

USERSWAP return code 16, 19 

USERVINT 212 

USERVOUT 212 

USERXLOG 212 

using locks 52, 127 

V 

value 232 

varying length character strings 

Cnmnvlc 112 

Cnmvlc 110 

defining 112 
VIEW command 5 
VIEW command processor 

full-screen capability 54, 132 
VSAM data base 1 8, 71 , 1 53 
VSAM data set 19 
VSAM empty file 11,19 
VSAM files 5,214 
VSAM input 11, 18 
VSAM I/O 9, 18, 19 
VSAM open failure 19 
VSAM output 11,19 
VSAM (keyed file access) 69, 150 
vsdata parameter 213 
vsdatlen parameter 213 
vsfunc parameter 213 
vskey parameter 214 
vsoption parameter 214 
vstring parameter 99, 101 
VTAM command invocation 11, 13 
VTAM level 210 
VTAM messages 11 
VTAM PPOLOG 15 



wildcard character 184 
WTOR command 203 

X 

XITBN 11 

XITBN user exit 16 

XITBO 11 

XITBO user exit 16 

XITCI 11 

XITCI user exit 17 

XITCO 11 

XITCO user exit 18 

XITDI 11 

XITDI user exit 18 

XITVI 11 

XITVI user exit 18 

XITVN 11 

XITVN user exit 19 

XITVO 11 

XITVO user exit 19 

XITXL 11 

XITXL user exit 19 



Numerics 

31-bit addressing mode 12 

Special Characters 

& (address) operator 93, 94 
&HDRMTYPE variable 204 
&LINETYPE variable 204 
&MSGID variable 204 
&MSGORIGIN variable 204 
&MSGSTR variable 204 
&PARMSTR 42 
&PAUSE function 53,130 



w 

W indicator 187 

WAIT 48, 53, 120, 130, 177 

WAIT command 36,186 

WAIT CONTINUE command 187 

WAIT FOR MESSAGES command 183 

WAIT FOR OPINPUT 35, 103 

WAIT side 73,157 

waiting and trapping 48, 120 
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